为不同的资源混合 REST API 复数和单数？

Question

REST api 的复数形式更自然，也更常用，例如/api/users 或 api/users/123。

但是对于某些资源是不自然的，例如：

• /api/login - 只登录一个用户
• /api/profile - 获取登录用户的个人资料

这些资源永远不会用于我的应用程序中的多个对象/模型。

另一方面，我了解到在资源名称中混合复数和单数形式并不是一种好的做法 (http://pages.apigee.com/web-api-design-ebook.html)。

所以我考虑怎么办：

1. 全部使用单数
2. 全部使用复数形式（使用一些愚蠢的形式，例如/api/logins）
3. 几乎所有资源都使用复数形式并不一致，因此需要一些特殊资源，例如 /api/login 或 /api/profile，它们始终与一个对象/模型一起使用。

什么是更好的方法？

Answer 1

定义 RESTful API 没有严格的准则，但我读得最多的是常识应该占上风。

因此，选项 3：

为了几乎所有资源都使用复数形式并使用复数形式，需要一些特殊资源，例如 /api/login 或 /api/profile，它们总是与一个对象/模型一起使用。

是最合乎逻辑的。当你认为“我需要资源 X，这个 URL 会是什么样子”时，你应该总能猜到 URL？

Answer 2

我并不是说我更喜欢复数，但如果你使用复数，你可以通过这种方式来协调你的特殊单数：

GET /api/forms/login 是 HTML 登录表单。从这个角度来看，login 是表单集合中的一个表单的 ID。

POST /api/forms/login 是提交登录表单的地方。

GET /api/users/{id}/profile 检索指定用户的配置文件。这适用于很多情况，但不适用于匿名网站，因为即使在查看用户个人资料时，用户的身份也应该保持隐藏，这可能会遗漏用户 ID 和真实姓名。

GET /api/profiles/{id} 将配置文件实体与用户 ID 分离，适用于匿名网站。

或者，您可以写 GET /api/users/current/profile 或 GET /api/sessions/current/profile 省略您帖子中的特定 ID，因为服务器会回复与当前用户相关的内容。

Answer 3

我在这些年从事的一些项目中看到的是，对于大多数常见操作而言，单数看起来更友好，例如，您可以为用户资源设置以下端点：

GET /user  --> retrieves all users
GET /user/{id} --> retrieves a user with the given id
POST /user --> inserts a new user (the user object will come in the request body)
PUT /user/{id} --> updates a user with the given id (the user object will come in the request body)
DELETE /user/{id} --> deletes the user with the given id

这些是常见的操作，当您有批量插入/更新/删除操作时，最好使用复数形式

POST /users  (the user objects will come in the request body)
PUT /users/{listOfIds}  (the user objects will come in the request body)
DELETE /users/{listOfIds}

GET /user 和 GET /users 是同义词，这两个将接受查询参数以优化结果，例如

GET /users?status=active

Answer 4

REST(Representational state transfer) 基本上是针对单个实体并对其进行 CRUD。所以使用单数对我来说更有意义。但是，如果您需要获取列表，那么复数是有意义的。例如：

你想得到一个用户然后有 /api/user/{id}

但如果你想获取用户列表，那么有 /api/users