链接到REST API中的另一个资源:通过其ID还是通过URL? [英] Link to another resource in a REST API: by its ID, or by its URL?

问题描述

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

I am creating some APIs using apiary, so the language used is JSON.

假设我需要代表此资源:

Let's assume I need to represent this resource:

{
    "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，/stores/3) )?

Is it correct to refer to other resources by their IDs (12, 1, 3), or I should specify the URL of these resources (i.e. /customers/12, /users/1, /stores/3)?

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

I am not using HATEOAS and I am a bit confused.

推荐答案

DO 包括您的响应中的绝对实体URI(例如/customers/12甚至http://www.example.com/customers/12).

DO include absolute entity URIs in your responses (such as /customers/12 or even http://www.example.com/customers/12).

请勿在响应中仅包含实体的ID(例如12)，因为那样您会强迫客户端自己将资源URI放在一起.为了做到这一点，他们需要预先了解存在的URI，并且您将失去对服务器端URI空间的控制.

DO NOT include just an entity's ID (such as 12) in a response, because that way you're forcing clients to put together resource URIs themselves. In order to do that, they would need to have prior knowledge of what URIs there are, and you're losing control over the URI space on the server side.

(如果服务器指示客户端如何操作，例如通过发送 URI模板以及ID；但如果这样做，它也可以发送结果URI.)

(Having the client put together an URI is OK if the server instructs the client how, e.g. by sending a URI template along with the ID; but if it did that, it could just as well send the resulting URI.)

• 文章"REST API必须是超文本的驱动"(由REST的发起人Roy T. Fielding 提出).请特别注意以下两个要点:

• Article "REST APIs must be hypertext-driven" by Roy T. Fielding (the originator of REST). Take note especially of these two bullet points:

• 在输入REST API时，除初始URI(书签)外，不应具有其他知识."
• " REST API不得定义固定的资源名称或层次结构(客户端和服务器之间明显的耦合).服务器必须具有控制自己的名称空间的自由.相反，允许服务器指示客户端如何构造适当的URI [.]"

• "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 ，它指定了将与相关资源的链接放入响应中的标准方法.

HAL, which specifies a standard way to put links to related resources into your responses.

JSON API — 在JSON中构建API的规范"

JSON API — "a specification for building APIs in JSON"

以上建议不仅适用于其他资源的ID(即外键"，例如您的customer_id)；您还将资源本身的id变成所谓的自我链接"；参见 SO问题超链接API中自链接的重要性是什么?" .

The above advice is not just for IDs of other resources (i.e. "foreign keys" such as your customer_id); you'd also turn the resource's own id into a so-called "self link"; see the SO question "What is the importance of the self link in hypermedia APIs?".

示例:

您的原始资源可以按以下方式重新设计:

Your original resource could be re-designed as follows:

{
  "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).

• Each resource (the main object being transferred, but also sub-resources) has some self-descriptive meta-data attached to it, such as type, id, links.
• Sub-resources can include partial or complete data. As long as the self-link is there, the client knows where to get the complete resource.
• The type might seem somewhat redudant; often, you implicitly know what kind of object to expect. This property can help in validation, and also gives you the opportunity to distinguish between object type and role (e.g. cashier is-a user in the above example).

这篇关于链接到REST API中的另一个资源:通过其ID还是通过URL?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！