REST API 设计中的查找或创建习惯用法? [英] find-or-create idiom in REST API design?

问题描述

假设我们有一个对 'name' 有唯一约束的 'user' 资源.您将如何设计 REST API 来处理查找或创建(按名称)用例?我看到以下选项:

say we have a 'user' resource with unique constraint on 'name'. how would you design a REST API to handle a find-or-create (by name) use case? I see the following options:

客户:

POST /user
{"name":"bob"}

服务器:

HTTP 409 //or something else

客户:

GET /user?name=bob

服务器:

HTTP 200 //returns existing user

选项 2:一个请求，两个响应代码

客户:

POST /user
{"name":"bob"}

服务器:

HTTP 200 //returns existing user

(如果用户实际创建，则返回 HTTP 201)

(in case user is actually created, return HTTP 201 instead)

客户:

POST /user
{"name":"bob"}

服务器:

HTTP 409 //as in option1, since no CREATE took place
{"id": 1, "name":"bob"} //existing user returned

推荐答案

我相信正确"的RESTful 方法是:

I believe the "correct" RESTful way to do this would be :

GET /user?name=bob
   200: entity contains user
   404: entity does not exist, so
        POST /user { "name" : "bob" }
           303: GET /user?name=bob
                200: entity contains user

我也是 Post-Redirect-Get 模式的忠实粉丝，这需要服务器使用新创建的用户的 uri 向客户端发送重定向.您在 POST 案例中的响应将在其正文中包含状态代码为 200 的实体.

I'm also a big fan of the Post-Redirect-Get pattern, which would entail the server sending a redirect to the client with the uri of the newly created user. Your response in the POST case would then have the entity in its body with a status code of 200.

这确实意味着 1 或 3 次往返服务器.PRG 的一大优势是在发生页面重新加载时保护客户端免于重新发布，但您应该阅读更多相关信息以确定它是否适合您.

This does mean either 1 or 3 round-trips to the server. The big advantage of PRG is protecting the client from rePOSTing when a page reload occurs, but you should read more about it to decide if it's right for you.

如果这与服务器来回太多，您可以执行选项 2.根据我对 https://www.rfc-editor.org/rfc/rfc2616#section-9.5:

If this is too much back-and-forth with the server, you can do option 2. This is not strictly RESTful by my reading of https://www.rfc-editor.org/rfc/rfc2616#section-9.5:

POST 方法执行的操作可能不会导致资源可以通过 URI 标识.在这种情况下，200 (OK) 或 204(No Content) 是适当的响应状态，取决于是否响应是否包含描述结果的实体.

The action performed by the POST method might not result in a resource that can be identified by a URI. In this case, either 200 (OK) or 204 (No Content) is the appropriate response status, depending on whether or not the response includes an entity that describes the result.

如果您可以偏离标准，并且担心往返，那么选项 2 是合理的.

If you're okay with veering away from the standard, and you're concerned about round-trips, then Option 2 is reasonable.

这篇关于REST API 设计中的查找或创建习惯用法?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！