json - 链接到 REST API : by its ID, 中的另一个资源或其 URL？

Question

我正在使用 apiary 创建一些 API ，所以使用的语言是 JSON。

让我们假设我需要代表这个资源:

{
    "id" : 9,
    "name" : "test",
    "customer_id" : 12,
    "user_id" : 1,
    "store_id" : 3,
    "notes" : "Lorem ipsum example long text"
}

通过 ID 引用其他资源( 12 、 1 、 3 )是否正确，或者我应该指定这些资源的 URL(即 /customers/12 、 /users/1 、 7 914| )

我没有使用 HATEOAS，我有点困惑。

Answer 1

做 包括 absolute响应中的实体 URI(例如 /customers/12 甚至 http://www.example.com/customers/12 )。

不要在响应中只包含一个实体的 ID(例如 12 )，因为这样您就迫使客户端自己将资源 URI 放在一起。为了做到这一点，他们需要事先了解有哪些 URI，而您将失去对服务器端 URI 空间的控制。

(如果服务器指示客户端如何，例如通过发送 URI template 和 ID，让客户端组合一个 URI 是可以的；但如果这样做，它也可以发送结果 URI。)

另见:

Article "REST APIs must be hypertext-driven" by Roy T. Fielding (REST的鼻祖)。请特别注意以下两个要点:

• "A REST API should be entered with no prior knowledge beyond the initial URI (bookmark)."
• "A REST API must not define fixed resource names or hierarchies (an obvious coupling of client and server). Servers must have the freedom to control their own namespace. Instead, allow servers to instruct clients on how to construct appropriate URIs[.]"

HAL ，它指定了将相关资源的链接放入响应中的标准方法。

JSON API — “在 JSON 中构建 API 的规范”

上述建议不仅适用于其他资源的 ID(即“外键”，例如您的 customer_id )；您还可以将资源转为自己的 id进入所谓的“自链接”；见 SO question "What is the importance of the self link in hypermedia APIs?" .

示例:

您的原始资源可以重新设计如下:

{
  "type": "foobar",
  "id": "9",
  "links": {
    "self": "//example.com/foobars/9"
  },
  "cashier": {
    "type": "user",
    "id": "1",
    "links": {
      "self": "//example.com/users/1"
    }
  },
  "customer": {
    "type": "customer",
    "id": "12",
    "links": {
      "self": "//example.com/customers/12"
    }
  },
  "name" : "test",
  "notes" : "Lorem ipsum example long text",
  "store": {
    "type": "store",
    "id": "3",
    "links": {
      "self": "//example.com/stores/3"
    }
  }
}

需要注意的几点:

每个资源(被传输的主要对象，还有子资源)都有一些附加的自描述元数据，例如 type , id , links .

子资源可以包括部分或完整的数据。只要自链接在，客户端就知道从哪里获取完整的资源。

type可能看起来有些冗长；通常，您隐含地知道期望什么样的对象。这个属性可以帮助验证，也让你有机会区分对象类型和角色(例如 cashier is-a user 在上面的例子中)。