链接到 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)引用其他资源是否正确，或者我应该指定这些资源(即/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 include 绝对 实体 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 必须是超文本-驱动"作者:Roy T. Fielding(REST 的创始人).请特别注意以下两个要点:

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

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

• 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，链接.
    • 子资源可以包含部分或完整数据.只要有自链接，客户端就知道从哪里获取完整的资源.
    • 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屋！