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

Question

我想在我的REST API中添加操作,以便在不同的"商店"之间移动"资源".

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

/resources
/resources/{resourceId}

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

1. '停用'资源,即使其在/ resources下不可用.从概念上讲,它将对象'移动'到' / resources/deactivated / '子文件夹:

   POST /resources/{resourceId}/deactivate   
   

   或者:

   POST /resources/deactivated/{resourceId}
   

2. 获取所有已停用的对象:

   GET /resources/deactivated      
   

3. 反转'deactivate'动作,即概念上将对象从' / resources/deactivated / '子文件夹移回主要文件夹(' / resources ').

   或

   POST /resources/{resourceId}/reactivate    
   

   要么

   POST /resources/deactivated/{resourceId}/restore     
   

   这个API对我来说似乎很直观.但它似乎违反了我在许多最佳实践中看到的"首选名词"规则 - 关于REST API的文章:我使用动词和形容词而不是名词!

请注意,我可能有所有端点的参数,例如GET/resources/deactivated？createdBefore = 01022017

我的REST API有更好的替代方案吗？即更多RESTful,但不是更直观的？

我能找到关于这个主题的好资源:

• 休息URL中名词与动词之间的混淆
• GitHub对动词的使用(POST/gists /:id/star,DELETE/gists /:id/star):https://stackoverflow.com/a/19648997/1847482
• 需要寻找'另一种对象类型'的好点:https://stackoverflow.com/a/2022938/1847482

Answer 1

首先,请记住REST代表Re presentational S tate T ransfer.

这完全取决于资源及其状态.操作如激活,关闭和搬迁都是关于用新的显示置换资源的当前状态,你不需要在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]为请求有效载荷中发送的资源的文件夹.