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

 

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

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

/resources
/resources/{resourceId}

现在假设我想'停用'一些资源，也就是从概念上将它移动到另一个子文件夹。 最直接的方法就是遵循这一点。

  • '取消'资源，即导致它在/资源下不可用。 从概念上讲，它将对象'移动'到'/ 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的文章：我使用动词和形容词来代替名词！

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

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

    我可以找到有关该主题的良好资源：

  • 名词与动词在其他网址中混淆
  • GitHub使用动词（POST / gists /：id / star，DELETE / gists /：id / star）：https：//stackoverflow.com/a/19648997/1847482
  • 需要查找“另一个对象类型”的好处：https：//stackoverflow.com/a/2022938/1847482

    • 首先，请记住， REST代表Re Reformationational 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]标识的资源的文件夹替换为在请求有效载荷中发送的资源的文件夹。

    活动资​​源是否与停用资源不同？ 考虑只有一个跟踪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}

    不要在/resources之后重载路径段的含义。

    感谢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或PUT

    链接地址: http://www.djcxy.com/p/40961.html

    上一篇: Alternatives of using verbs and adjectives in RESTful URL

    下一篇: URL design for advanced filtering of results in restful API