在 RESTful API 中引用 URL

Question

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

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

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

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

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