我应该在REST API响应中包含URL或ID资源吗？

Question

我正在设计一个REST API。有一个实体组织，可能有一个父组织和多个子组织。

假设用户请求GET /organizations/1234。 我该怎么回应？

我可以将URL用于这些其他组织。

{
  "data": {
    "name": "Microsoft",
    "parent_organization": "http://api.myapi.asdfghj/organizations/1220",
    "child_organizations": [
      "http://api.myapi.asdfghj/organizations/1236",
      "http://api.myapi.asdfghj/organizations/1214"
    ]
  }
}

或者我可以使用他们的ID

{
  "data": {
    "name": "Microsoft",
    "parent_organization": 1220,
    "child_organizations": [
      1236,
      1214
    ]
  }
}

哪一个更好？

如果是带有完整网址的那个，我该怎么做才能大摇大摆？我只是将其设置为字符串，如下所示吗？

definitions:
  Organization:
    type: object
    properties:
      data:
        type: object
        properties:
          name:
            type: string
          parent_organization:
            type: string
            format: url
          child_organizations:
            type: array
            items:
              type: string
              format: url 

创建新用户的POST /organizations怎么样？用户是否应将父项和子项指定为URL？

Answer 1

我建议您使用网址而不是某些ID。拥有实际网址的优势在于您可以动态更改它们，而无需担心依赖某些基本网址的客户端，然后必须从ID等计算实际网址。

出于文档目的，您可以将网址视为字符串，并像其他参数一样解释它们。