REST 的资源和操作 URI 约定

Question

我正处于开发一些 REST API 的十字路口，我发现没有关于这个主题的真正讨论，更不用说对两者的坚定辩护了。

据我了解，使用 REST，您可以将其/<resource>/<action>作为 URL

因此，要禁用用户，您将拥有：

PUT /user/disable

似乎有道理。但是，我们正在讨论更基本的方法：

应该是：

POST /user  (creates a user *implicitly*)
POST /user/create (creates a user *explicitly*)

DELETE /user/:id
DELETE /user/:id/delete

第一个似乎被认为是“标准”，第二个在意图上显然要明确得多，并且与 /user/disable 等方法一致

也许这场辩论在其他地方已经很激烈了，但我还没有看到。如果您对此有“宗教信仰”，那么现在是您发表意见的机会

Answer 1

拥有/<resource>/<action>您的 URL 不是 REST。REST 使用 HTTP 动词来确定要对给定资源或资源集合执行的操作。这意味着：

• 创建资源是： POST /users
• 阅读资源是： GET /users/<id>
• 更新（实际替换）资源是： PUT /users/<id>
• 删除资源是： DELETE /users/<id>

那就是休息。

对于所有其他方法，您可以使用其他动词，如PATCH. 禁用用户可能是：

PATCH /users/<id>/disable

这不是纯粹的 REST，但没关系。

编辑：如果您想符合 REST，禁用用户意味着您要更改他的状态。换句话说，您想要更改其属性之一，例如state标志。您可以“修补”您的资源：

PATCH /users/<id>?state=disabled

这就是休息。您还可以PUT按照评论中的说明使用来替换资源。

Answer 2

@克里斯蒂安·邦吉奥诺

您正在对与 REST 无关的 URI 中的操作进行编码。这是一种最清晰的 RPC 形式。

您需要识别资源并使用您使用的底层协议（即您的情况下的 HTTP）中定义的方法对这些资源执行操作。HTTP 规范定义了这些方法的语义，因此您必须执行以下操作，而不是直接在 URI 中编码操作：

• GET /users - 返回用户列表（每个条目/项目都有自己的特定用户链接）
• GET /users/:id - 返回特定用户
• POST /users - 在 /users 资源下创建新用户
• POST /users/:id - 编辑用户（或者可以在此处使用 PATCH 方法）
• PUT /users/:id - 替换用户
• DELETE /users/:id - 删除用户

这就是你应该如何思考行动。但这还不够，您需要使用为链接等超媒体控件（至少）提供支持的媒体格式，以便能够描述这些操作，例如，请参阅：

• HAL - http://stateless.co/hal_specation.html
• Collection.JSON - http://amundsen.com/media-types/collection/format/
• 链接关系注册表 - http://www.iana.org/assignments/link-relations/link-relations.xml

一些快速交互示例：

***Request***
GET /users HTTP/1.1
Host: service.org
Accept: application/x+json

***Response***
HTTP/1.1 200 OK
Content-Type: application/x+json
Content-Length: ...

[{
  "name": "john",
  "links": {
    "self": "/users/1",
    "edit": "/users/1"
  }
}, {
  "name": "jane",
  "links": {
    "self": "/users/2",
    "edit": "/users/2"
  }
}]

***Request***
GET /users/2 HTTP/1.1
Host: service.org
Accept: application/x+json

***Response***
HTTP/1.1 200 OK
Content-Type: application/x+json
Content-Length: ...
{
  "name": "jane",
  "links": {
    "self": "/users/2",
    "edit": "/users/2"
  }
}

***Request***
DELETE /users/2 HTTP/1.1
Host: service.org

***Response***
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: ...

Resource was destroyed...

***Request***
POST /users/2 HTTP/1.1
Host: service.org
Content-Type: application/x+json
Content-Lenght: ...

{"status": "disabled"}

***Response***
HTTP/1.1 303 See Other
Location: /users/2