java - RESTful 服务设计 : Calling get all resource endpoint

Question

寻找一些建议来帮助我设计一个 Restful 服务。

1. 获取所有产品:当客户尝试获取所有产品 /products 时会发生什么。我应该退回所有产品还是前 50 件？
2. 如果服务会返回前 50 或前 100，那么我应该在哪里编写分页逻辑？我应该用相同的 getAllProducts() 方法编写吗？
3. 我还计划拥有 sort 和 search 功能。这两个会去哪里？

这是我的假设:

@RequestMapping("/products")
public String getAllProducts(@QueryParam(value="page") int page, @QueryParam(value="sort") String orderBy) {

@RequestMapping("/search/products")
public String findProducts(@QueryParam(value="q") String searchCriteria) {

Answer 1

正如您所建议的，常规做法是使用参数。
根据您的要求，您可以使用以下之一:

1. ?page=$pagenumber(页面大小由您定义)
2. ?page=$pagenumber?per_page=$pagesize(页面大小由客户定义)(这就是 GitHub 的做法)
3. ?start=$idOfFirstElement?per_page=$idOfLastElement(没有“人工”页面，更接近数据库)

当然你可以(或者也许应该)限制变体 2 和 3 的输入，如果结果太大，返回一个 #4XX 响应代码。

---

1. Get all Products: what happens when a client tries to get all the products /products. Should I return all the products or first 50?

常规和预期的 RESTful 行为是获取所有产品，而在真实环境中这通常是不可能的。 (想想拥有 10k 种产品的“小型”网上商店)。
基本上你有两种设计选择:

1. 没有分页信息的 HTTP 请求是错误的。给出一个 #4XX 响应。
2. 没有分页信息的 HTTP 请求使用默认值。 (例如首页和每页 50 个产品)

我建议使用第一个，因为它看起来更干净并且不会让客户感到困惑。

---

3. I am plan to have sort and search functionality as well. Where would these two go?

与页面参数相同。只需将它们添加到 URI。
例如?sortBy="价格" ?sort="ASC" ?sort="DESC" ?searchFor="lalalala"

---

2. If the service will return the first 50 or the first 100, then where should I write the pagination logic? Should I write it in the same getAllProducts() method?

遗憾的是，我们无法用您提供的少量给定代码对此做出真正的评论。 ...而且 SO 不是真正的 Code Review