如何在符合REST原则的前提下尽可能有效地处理集合的REST API问题

Question

我对REST不太了解，但根据我收集到的信息，以下URL符合REST原则。资源布局如下：

/user/<username>/library/book/<id>/tags
          ^         ^           ^   ^
          |---------|-----------|---|- user resource with username as a variable
                    |-----------|---|- many to one collection (books)
                                |---|- book id 
                                    |- many to one collection (tags)


GET /user/dave/library/book             //retrieves a list of books id's
GET /user/dave/library/book/1           //retrieves info on book id=1
GET /user/dave/library/book/1/tags      //retrieves tags collection (book id=1)

然而，如何优化这个示例API呢？比如说我的图书馆里有1万本书，我想获取每一本书的详细信息。我是真的需要在/library/book中为每一个id强制进行一次http调用吗？还是应该将多个id作为参数启用？/library/book/<id1>,<id2>... 并且像批量获取那样一次性获取100个id？

REST原则对这种情况有什么说法？你有什么看法吗？

再次感谢。

- netbrain

---

REST对于URL的外观没有任何意见。然而，这个文档提供了一堆建议：http://tools.ietf.org/html/draft-gregorio-uritemplate-04 - Darrel Miller

请查看此链接以了解设计RESTful API的一些最佳实践：saipraveenblog.wordpress.com/2014/09/29/rest-api-best-practices - java_geek

Answer 1

这纯粹是一个设计问题。

我可以定义一个bookc资源，并像这样使用它：

GET /user/dave/library/book?bookList=...

如何进一步指定bookList参数，实际上取决于你对此资源的使用方式。例如，你可以：

GET /user/dave/library/book?bookList=1-10
GET /user/dave/library/book?bookList=1,2,5,20-25

或者你可以简单地翻阅所有的书籍：

GET /user/dave/library/book?page=7&pagesize=50

但在我看来，特别是带有一长串“随机”id的表单似乎不太合适。也许我会定义一个filter参数，这样我就可以指定：

GET /user/dave/library/book?filter=key,value&filter=key,value

关于HTTP URL长度限制的问题，标准并没有设定任何限制。但是浏览器可能会有所不同...请参考这个S.O.主题。

为了更加严格地遵循RESTful，可以通过HTTP头指定查询参数，但我想要传达的一般思想并没有改变。

希望这对您来说合适...

- sergio

---

请查看以下 Stack Overflow 主题：https://dev59.com/GHVC5IYBdhLWcg3wZwTj - sergio

你会如何格式化ID？逗号分隔？查询字符串中可以放置多少数据的限制是什么？使用POST和POST参数是否更好（允许）？ - netbrain

我会避免在HTTP头中指定查询参数，因为这意味着(a)您可以有多个完全不同但共享相同URI的查询，以及(b)它将删除中间代理缓存查询结果以提高性能的能力。 - Brian Kelly

我更倾向于使用以下URL作为您的资源/users/dave/books/。 - java_geek

Answer 2

看起来不错，但是我会改为复数形式的名称，这样读起来更好：

/users/{username}/books/{bookId}

我不理解传递逗号分隔的id列表的用例。问题是如何获取这些id？我猜在id列表背后有语义，即它们代表过滤器的结果。因此，我会使用搜索API而不是传递ids。简单的示例：

/users/dave/books?puchasedAfter=2011-01-01
 

如果您想遍历您的10K本书的收藏，请使用分页参数。

- manuel aldana

Answer 3

你可以使用分页器

一些RESTful API与分页器一起使用，用于处理大量资源，例如：

http://example.org/api/books?page=2

服务器每页提供100条记录（例如图书），您可以在get请求中使用sortby对图书进行排序。使用上述请求，如果数据库中有这么多书，则将获得第101-200本书。响应可以告诉您有关书的数量和页面数量、下一页和上一页，但接下来您还需要了解更多关于HATEOAS的知识。

否则，如果您想获取特定ID，则可以像这样操作：

http://example.org/books?id=[]2&id=[]5&id=[]7&id=[]21

一个带有 id 数组的 GET 请求（id = [2,5,7,21]），返回对应 id 的书籍。

- Wilt

Answer 4

这只是我的个人观点：

GET /user/dave/library/book/IDList      //retrieves a list of books id's
or
GET /user/dave/library/bookID           //retrieves a list of books id's

GET /user/dave/library/book             //retrieves a list of books
GET /user/dave/library/book/1           //retrieves info on book id=1
GET /user/dave/library/book/1-3         //retrieves info on book id>=1 and id <=3
GET /user/dave/library/book/1/tags      //retrieves tags collection (book id=1)

- Volkmar Rigo