Question

我想在我的REST API中添加操作，以便在不同的“商店”之间移动“资源”。

例如，假设我的资源通常由以下URL访问：

/resources
/resources/{resourceId}

现在假设我想'停用'某些资源，即从概念上将其移动到另一个子文件夹。允许这种情况的最直接方式如下：

'停用'资源，即使其在/ resources下不可用。从概念上讲，它将对象'移动'到' / resources / deactivated / '子文件夹：
```
POST /resources/{resourceId}/deactivate   
```
或者：
```
POST /resources/deactivated/{resourceId}
```
获取所有已停用的对象：
```
GET /resources/deactivated      
```
撤消'停用'操作，即从概念上将对象从' / resources / deactivated / '子文件夹移回主要文件夹（' / resources '）。

无论
```
POST /resources/{resourceId}/reactivate    
```
或者
```
POST /resources/deactivated/{resourceId}/restore     
```
这个API对我来说似乎很直观。但它似乎违反了我在许多最佳实践中看到的“首选名词”规则 - 关于REST API的文章：我使用动词和形容词而不是名词！

请注意，我可能拥有所有端点的参数，例如获取/资源/已停用？createdBefore = 01022017

我的REST API还有更好的选择吗？即更多RESTful，但不是那么直观吗？

我可以在这个主题上找到很好的资源：

Confusion Between Noun vs. Verb in Rest URLs
GitHub使用动词（POST / gists /：id / star，DELETE / gists /：id / star）：https://stackoverflow.com/a/19648997/1847482
需要寻找'另一种对象类型'的好点：https://stackoverflow.com/a/2022938/1847482

Answer 1

首先，请记住 REST 代表重新表示 S tate T 传输。

所有关于资源及其状态。激活，取消激活和移动等操作都是关于使用新表示替换资源的当前状态而您不需要动词在URL中表达此类操作。

例如，要替换资源的状态，您可以在PUT请求的有效负载中发送资源的新表示：

PUT /api/resources/[id]/status HTTP/1.1
Host: example.org
Content-Type: application/json

{ "status" : "active" }

可以理解为将[id]标识的资源的状态替换为请求有效负载中发送的资源。

然后，您可以使用以下内容来获取具有特定状态的资源：

GET /api/resources?status=active HTTP/1.1
Host: example.org
Accept: application/json

可以理解为让我代表状态为active 的所有资源。

例如，要将资源移动到另一个文件夹，您可以：

PUT /api/resources/[id]/folder HTTP/1.1
Host: example.org
Content-Type: application/json

{ "target" : "draft" }

可以理解为将[id]标识的资源的文件夹替换为请求有效负载中发送的文件夹。

Answer 2

活动资源是否真的与已停用的资源不同？考虑只有一个跟踪active的属性。您可以随时过滤掉它们，例如

GET /things?active=true

您可以使用microPUT

更改该属性

PUT /things/{id}/active
false

如果thing和deactivated-thing在概念上不同，那么拥有两个单独的端点是合理的。我会使用

在它们之间移动

POST `/deactivated-things`
{
    "thing": "/things/12"
}

和

POST `/things`
{
    "deactivated-thing": "/deactivated-things/12"
}

您应该尽量避免使用具有多重含义的路径。例如，不要这样做：

/resources/{id}
/resources/deactivated/{id}

请勿在{{1}}之后重载路径段的含义。

Answer 3

感谢Cassio强调'改变对象状态'的方法。

我自己对完整性的回答：

PATCH /resources/{resourceId} with body {"active":false}  -- deactivate a resource
PATCH /resources/{resourceId} with body {"active":true}  -- restore a resource
GET    /resources                        -- return all 'normal' resources
GET    /resources?includeInactive=true   -- return all resources including the deactivated ones
GET    /resources/{resourceId}           -- return the resource

（'GET'检索的资源将包含属性'active = true / false'）。

似乎是PATCH的经典案例：REST API PATCH or PUT

Answer 4

REST中从未提及的一件事：

不要将REST与Web应用程序或漂亮的URL混淆。

例如当用户登录以编辑其帐户时，您将显示

www.example.com/home
www.example.com/account
www.example.com/profile

不是

// www.example.com/users/{id} ...
www.example.com/users/433563444335634443356344
www.example.com/users/433563444335634443356344/edit

我认为这是许多开发人员感到困惑的地方。 REST非常适合API，但是就网络应用而言，它应该用作表单操作端点或ajax的内部API，但不一定要用作漂亮的url。

在RESTful URL中使用动词和形容词的替代方法

4 个答案: