在RESTful URL中使用动词和形容词的替代方法 [英] Alternatives of using verbs and adjectives in RESTful URL

问题描述

我想向我的REST API添加可以在不同商店"之间移动资源"的动作.

I want to add actions to my REST API that would move 'resources' between different 'stores'.

例如，假设我的资源通常可以通过以下URL访问:

For instance, suppose my resources are normally accessed by the following URL:

/resources
/resources/{resourceId}

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

Now suppose I want to 'deactivate' some resource, i.e. conceptually move it to another sub-folder. The most straightforward way to allow this would be as followed.

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

POST /resources/{resourceId}/deactivate   

或者:

POST /resources/deactivated/{resourceId}

获取所有停用的对象:

Get all the deactivated objects:

GET /resources/deactivated      

撤消停用"操作，即从概念上将对象从"/resources/deactivated/"子文件夹移回主文件夹("/resources ").

Reverse the 'deactivate' action, i.e. conceptually move the object from the '/resources/deactivated/' subfolder back to the main one ('/resources').

任何一个

POST /resources/{resourceId}/reactivate    

或

POST /resources/deactivated/{resourceId}/restore     

这个API对我来说似乎很直观.但这似乎违反了我在REST API的许多最佳实践文章中看到的首选名词"规则:我用动词和形容词代替名词！

This API seems rather intuitive for me. But it seems to violate the 'prefer nouns' rules that I have seen in many best practices-articles on REST API: I use verbs and adjectives instead of nouns!

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

Note that I might have parameters for all the endpoints, e.g. GET /resources/deactivated?createdBefore=01022017

我的REST API是否有更好的替代方法? IE.更多RESTful，但又不那么直观?

我可以在该主题上找到很好的资源

Good resources that I could find on the topic:

• 名词与动词之间在静态URL中的混淆
• GitHub上的动词用法(POST/gists/:id/star，DELETE/gists/:id/star): https://stackoverflow.com/a/19648997/1847482
• 关于需要查找另一种对象类型"的要点: https://stackoverflow.com/a/2022938/1847482

• Confusion Between Noun vs. Verb in Rest URLs
• GitHub's usage of verbs (POST /gists/:id/star, DELETE /gists/:id/star): https://stackoverflow.com/a/19648997/1847482
• Good point on needing to look for 'another object type': https://stackoverflow.com/a/2022938/1847482

推荐答案

首先，请记住 REST 代表 Re 代表性 S 泰特 T 转移.

First of all, remember that REST stands for Representational State Transfer.

这全都与资源及其状态有关. activate ， deactivate 和 move 之类的操作都是关于用新的表示形式替换资源的当前状态，而您不需要动词在网址中表示此类操作.

It is all about resources and their state. Operations such as activate, deactivate and move are all about replacing the current state of the resource with a new representation and you don't need verbs in the URL to express such operations.

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

For example, to replace a status of a resource, you can send a new representation of the resource in the payload of a PUT request:

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

{ "status" : "active" }

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

It can be understood as replace the status of the resource identified by [id] with the one sent in the request payload.

然后，您可以通过以下方式获取具有特定状态的资源:

Then you could have the following to get the resources with a particular status:

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

可以理解为给我所有状态为active 的资源的表示.

It can be understood as give me a representation of all resources with the status active.

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

To move a resource to another folder, for example, you could have:

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

{ "target" : "draft" }

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

It can be understood as replace the folder of the resource identified by [id] with the one sent in the request payload.

这篇关于在RESTful URL中使用动词和形容词的替代方法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！