我应该在 REST API 响应中包含资源的 URL 或 Id 吗？答案

【问题标题】：Should I include URLs or Ids of resources in REST API response?我应该在 REST API 响应中包含资源的 URL 或 Id 吗？
【发布时间】：2016-03-15 12:23:12
【问题描述】：

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

假设用户请求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
    ]
  }
}

哪个更好？

如果它是具有完整 URL 的那个，我该如何大摇大摆地记录它？我是否只是将其设置为字符串，如下所示？

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？

【问题讨论】：

标签： rest swagger

【解决方案1】：

我建议你使用 url 而不是一些 id。拥有实际 url 的好处是您可以动态更改它们，而不必担心依赖于某些基本 url 的客户端然后必须从 id 等计算实际 url。

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

【讨论】：

POST /organizations 创建新用户怎么样？用户是否也应该将父项和子项指定为 url？
如果在您的情况下，网址永远不会改变，那么我认为您不需要将它们指定为网址。只传递 Id 听起来不错，但是如果您想在不同的端点托管这些不同的实体，那么 url 是更好的选择。