在 RESTful API 中引用 URL

Posted 2023-02-27

【中文标题】在 RESTful API 中引用 URL

【英文标题】：Referring to URLs in RESTful APIs

【发布时间】：2012-06-02 23:42:41

【问题描述】：

这里有几个 RESTful API 的标准 URL。

http://api.example.com/user/123 http://api.example.com/users

第一个检索单个用户，第二个检索用户集合（比如说 20 个）。

指代这些 URL 的“REST”术语是什么？将它们称为资源是否正确？如果第一个是资源，那么第二个应该是资源集合还是应该只是集合类型的资源？

【问题讨论】：

更准确地说：URL 是一个定位器或标识符。 URL 不是资源，它指的是资源。

【参考方案1】：

RESTful 应用程序上的每个 URI 都是一个资源，这个描述就足够了。

链接到相同类型的多个资源的资源可以称为集合，但没有正式名称。每个资源，无论是否是集合，都可以有链接。

资源之间的链接是 RESTful 系统的超媒体部分。最近，为此出现了一个新术语：HATEOAS，超媒体作为应用程序状态的引擎。

以复数形式命名集合是一种常见的良好做法，因此您的/users/ 示例似乎是正确的。用户 123 是 users 集合的子级，因此最好将其放在 /users/123 的复数形式下。

一个 RESTful、HATEOAS 应用程序将响应 /users/ 上指向单个资源的链接列表。比如：

    "links": [
        
            "href" : "/users/123/"
            "title" : "Alexandre Gaigalas"
        ,
        
            "href" : "/users/125/"
            "title" : "John Doe"
        ,
    ]

或者在 XML 中：

<link href="/users/123" title="Alexandre Gaigalas">
...

除了 JSON 中的 links 对象或 XML 中的标签之外，还可以提供其他信息。

这些链接稳定了资源之间的 RESTful 超媒体关系。我给出的示例大多是集合和个体之间的分层，但也可以声明其他类型的链接：

<link href="/users/123/picture.jpg" title="Alexandre Gaigalas avatar" rel="picture">

collection 术语主要是为抽象编程语言中的 RESTful 实现而创建的，因此开发人员可以更轻松地对类似资源的组进行分组和操作。

如果存在，查询字符串参数也会标识不同的资源，因此/users/?since=2009 与/users/ 不同。它们都是不同的资源，尽管非常相似。

片段标识符，即使没有发送到服务器，也被视为不同的资源，因此/users/123#bio 与/users/123 不同。

如果可能，更有意义的分页会更好。页码很难以 REST 方式处理，因为它们变化很大。如果有一个经常更新的集合（例如 *** 问题的列表），则第一页经常更改，用户可能会丢失从第 1 页更改为第 2 页的项目。大多数集合可以按日期或字母顺序分页。递增页码并没有错，但有更好的机制。

【讨论】：

如果URI包含参数（即http://api.example.com/users?limit=5&offset=10），将其称为资源是否仍然正确？如果是，该资源的名称是什么？还是“用户”吗？

完成了 =) 希望能有所帮助！

将任何 URL 称为资源是正确的！ RESTful 是指该资源遵循 REST 架构风格，该风格基于 5 个原则：客户端-服务器、无状态、可缓存、分层和统一。

更直观。如果有人登陆/users/123/，这个家伙可以很容易地预测/users/ 可能也会起作用。它类似于文件夹，用户在某种程度上更熟悉这种命名方式。

另外，超媒体中的链接更容易。由于链接可以是相对的，如果用户点击/users/，则链接可以是href=123。如果复数/单数不匹配，则链接必须类似于href=/user/123，更详细。