在 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:

• Rest URL 中名词与动词的混淆
• GitHub 的动词用法(POST/gists/:id/star, DELETE/gists/:id/star):https:///stackoverflow.com/a/19648997/1847482
• 需要寻找另一种对象类型"的好处:https://stackoverflow.com/a/2022938/1847482

推荐答案

首先，请记住 REST 代表 Representational State T转移.

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

这完全是关于资源及其状态.activate、deactivate 和 move 等操作都是用新的表示替换资源的当前状态，您不需要动词在 URL 中表示此类操作.

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]标识的资源状态替换为请求payload中发送的状态.

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]标识的资源所在文件夹替换为请求payload中发送的文件夹.

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屋！