API RESTful 资源命名

Question

当我需要为 REST API 创建资源 URL 时，我总是怀疑您可以在下面看到。我想知道是否有人可以帮助我。

假设我有两个模型。

• 用户
• 发布

用户可以提交自己的帖子，也可以评论自己的帖子和其他帖子。

用户的主要资源 URL 是：

GET  /users                     # Retrieve all users.
POST /users                     # Create a new user.
GET/DELETE/PUT /users/{user_id} # Get, remove and update an user.

Post 的主要资源 URL 为：

GET  /posts                     # Retrieve all posts.
POST /posts                     # Create a new post.
GET/DELETE/PUT /posts/{post_id} # Get, remove and update a post.

我的问题出现在我想要的时候：

前 10 名提交者（过滤参数（外部链接、讨论、全部））。网址应为：

GET /users/top?type=ext
GET /users/top?type=disc
GET /users/top # for all

或者应该是：

GET /users?top=ext
GET /users?top=disc
GET /users?top=all

相同，但有帖子：

前 10 条评论帖子（过滤参数（外部链接、讨论、全部））。网址应为：

GET /posts/comments?type=ext
GET /posts/comments?type=disc
GET /posts/comments # for all

或者应该是：

GET /posts?top=ext
GET /posts?top=disc
GET /posts?top=all

以上任何一个选项对您有好处还是应该是另一种方式？

问候

Answer 1

我喜欢将 REST URI 本身视为模型表示。

所以/users/top 没有多大意义，但/posts/comments 似乎没问题（因为 cmets 也可能是不同的模型）。但是对于您的情况，我推荐其他一组查询参数，因为它们广泛用于过滤和排序请求。所以在你的情况下，我会推荐类似的东西：

GET /users?sort=ext&order=desc&limit=10

这将帮助我了解我正在请求 10 个user 资源，这些资源已按descending 顺序为ext 排序。 （如果需要，您甚至可以将其更改为 type=ext）

Answer 2

像往常一样； REST 不在乎您使用什么拼写。

您可能会寻找灵感的一个地方是......堆栈溢出本身。这些 URI 是不是很眼熟？

/questions?sort=newest
/questions?sort=featured
/questions?sort=votes

API 有pretty decent documentation，它还会提供适当的拼写提示以处理分页和搜索范围。

也就是说，IMDB 采用了不同的方法 - The Shawshank Redemption 使用直截了当的“我是集合的元素”拼写

http://www.imdb.com/title/tt0111161/

但是一直以来的top rated titles？它们显示为图表

http://www.imdb.com/chart/top

但我想知道根据@Hawkes 的回答是否有标准，或者根本没有标准。

根本没有标准；只是当地的拼写约定。这在某种程度上是 REST 的一部分：服务器可以使用任何有意义的 URI 拼写，而客户端只是根据其对媒体类型和所提供数据的处理规则的理解“跟随其鼻子”由服务器。