在 REST 中，当资源被分页时，应该如何处理对 findAll 操作的 GET 请求？

Question

在 RESTful 服务中，无法一次全部检索的资源会被分页。例如：

GET /foo?page=1

问题是，我应该如何处理 getAll 请求，例如：
GET /foo

考虑到可发现性/HATEOAS，我看到了几个选项：

1. 返回 405 Method Not allowed 并在首页包含一个 Link 标头： Link=; rel=”first“
2. 返回 400 Bad Request 并包含链接标头（与上面相同）
3. 返回 303 See Other 到第一个分页页面
4. 返回200 OK 但实际上只返回第一页（并将下一页的 URI 包含到链接中）： Link=; rel =“下一个”
   • 注意：我宁愿不这样做，因为我知道如果客户没有明确要求，默认情况下不会为客户管理任何事情。

这些当然只是一些选择。我倾向于第一种，但我不确定是否有我不知道的最佳实践。 如有任何反馈，我们将不胜感激。 谢谢。

Answer 1

让我们首先了解一个事实：REST 并不是像 SOAP 那样的一成不变的协议，它只是一种构造服务的方法，类似于语言被描述为面向对象的方式。

综上所述，我建议按如下方式处理。

---

将 RESTful 调用视为函数声明。

GET /foo
foo()

有些函数需要参数。

GET /foo?start=??&count=??
foo(start, count)

有些语言支持默认参数，有些则不支持；您可以自己决定如何处理参数。

使用默认参数，您可以假设该函数被定义为

foo(start = 0, count = 10)

对 GET /foo 的调用实际上相当于 GET /foo?start=0&count=10 >，而调用 GET /foo?start=100 相当于 GET /foo?start=100&count=10。

如果您不想要默认参数，您可以强制 API 用户显式设置 start 和 count：

foo(start, count)

以便调用GET /foo 将返回 400 Bad Request 状态代码，但调用 GET /foo?start=0&count=10 将返回200 OK 状态代码以及包含的内容按指定范围。

在任何一种情况下，您都必须决定如何处理错误，例如

GET /foo?start=-10&count=99999999

如果参数有最大值和最小值，您将需要决定是规范化参数，还是简单地返回错误。前面的示例可能会返回 400 Bad Request 状态代码，但它也可能会被限制为：

GET /foo?start=0&count=1000

最后由您决定什么在您的应用程序上下文中最有意义。

Answer 2

从 RESTful 的角度来看，我认为以相同的方式处理这两种表示是完全可以的。考虑一个您想要下载的有多个版本的软件，最新的版本是 3.8。因此，如果您想获取最新版本，可以使用 GET /software/version/latest.zip 和 GET /software/version/3.8.zip 来解决，直到有一个更新的版本。因此两个不同的链接指向同一个资源。

我喜欢想象分页几乎是一样的。第一页总是有最新的文章。因此，如果没有提供 page 参数，您可以简单地暗示它是 1。

使用 rel 属性的方法的方向略有不同。它是 Google 为更好地处理重复内容问题而创建的，主要用于区分“主”页面和分页页面。以下是如何使用它：

//first page:
<link rel="next" href="http://www.foo.com/foo?page=2" />

//second page:
<link rel="prev" href="http://www.foo.com/foo?page=1" />
<link rel="next" href="http://www.foo.com/foo?page=3" />

//third and last page:
<link rel="prev" href="http://www.foo.com/foo?page=2" />

因此，从 SEO 的角度来看，使用这些元素是一个好主意（并且由 Google 推荐）。它们还与 REST 的面向资源的思想和资源的超媒体表示完美契合。

选择您的建议之一，我认为 303 See Other 是正确的选择。它旨在用于此类目的，并且是规范化资源的好方法。您可以通过许多 URI 来提供它们，但只有一个“真实”URI 来表示（就像具有不同版本的软件）。

根据规范，响应应如下所示：

303 See Other
Location: http:www.foo.com/foo?page=1

<a href="http:www.foo.com/foo?page=1">http:www.foo.com/foo?page=1</a>

因此，您提供具有“真实”表示形式的位置标头，并且正文应包含链接到新 URI 的超文本文档。请注意，根据规范，客户端预期向位置值发送 GET 请求，但实际上并非必须。

---

//编辑作为对您评论的回答（是的，在没有证明的情况下声称某些东西是非常糟糕的做法:-) - 我的错！）：

Google 提出了 rel="next" 和 rel="prev" 属性于 2011 年 9 月在 官方网站站长中心博客。它们还可以额外用于（或在某些情况下代替）rel="canonical" 标签。

在这些链接下，您可以找到它们之间的差异解释：

• rel="next" 和 rel="prev" 链接元素 是“指示分页系列中组件 URL 之间的关系”
• 这rel="canonical" “允许您公开指定您首选的 URL 版本”，

因此它们之间存在细微差别。因此，您可以将问题分解为规范问题：有多个 URL 指向同一资源（/foo 和 foo?page=1 但您有一个首选版本URL 的 (foo?page=1)，现在有一些 RESTful 方法的选项：

• 如果查询中没有给出 page 参数，请使用我认为处理它时有一个默认值（例如1）。 即使您指出这是不好的做法，也可以使用默认值。
• 在这种特定情况下， .3.4" rel="nofollow">303 See Other 在 Location 标头中提供首选 URL（如所述 是处理重复/规范内容的最佳方式（并且很可能是 REST 方式）。
• 我认为 3xx响应 org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1" rel="nofollow">400 错误请求以防万一想要强制客户端提供一个 page 参数（如 zzzzBov 在他的回答中所解释的）。请注意，此响应没有诸如位置标头之类的内容（如您的问题中假设的那样），因此请求失败的原因和/或正确的URL（如果给出）的解释) 必须转到响应的实体主体。另请注意，根据规范，当客户端提交错误/格式错误的表示（！不是 URL！）以及 PUT 或 POST 请求时，通常会使用此响应。因此请记住，这对于客户来说也可能有点模糊。

就我个人而言，我不认为您建议使用 进行响应405 Method Not allowed 是个好主意。根据规范，您必须提供一个Allow标头，列出允许的方法。但是该资源可以使用哪些方法呢？我只能想到POST。但是，如果您也不希望客户端POST到它，您也可以使用 403 Forbidden 并解释为什么禁止它，或 404 Not Found 如果您不想说出为什么它被禁止。所以它也可能有点模棱两可（在我看来）。

正如您在问题中提出的那样，将 link-elements 与提到的 rel-attributes 一起使用本质上并不是“RESTful”，因为它只是在资源表示中解决的超媒体。但您的问题（据我了解）是您想要决定如何响应特定请求以及服务哪个表示。但这仍然不是绝对没有意义的：

您可以将整个 SEO 问题视为使用 rel="next/prev/canonical" 的副作用，但请记住，它们也会创建连接性< /em> （作为链接的质量）这是 REST 的特征之一（参见 罗伊·菲尔丁的论文）。

如果您想深入研究 RESTful Web 服务（这是完全值得的），我建议您阅读这本书RESTful Web 服务 作者：Leonard Richardson 和 Sam红宝石。

Answer 3

在某些情况下，不隐式地为客户端管理任何内容可能会导致覆盖复杂的界面，例如消费者不具备技术能力或不打算在界面之上构建的情况，例如在网页中。在这种情况下，甚至 200 也可能是合适的。

在其他情况下，我同意隐式管理是一个坏主意，因为消费者希望能够正确预测响应，并且可能需要简单的规范。在这种情况下，405、400 和 303。

这是一个上下文问题。