36

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:

option 1: multiple requests

client:

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

server:

HTTP 409 //or something else

client: 

GET /user?name=bob

server:

HTTP 200 //returns existing user

option 2: one request, two response codes

client:

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

server: 

HTTP 200 //returns existing user

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

option 3: request errs but response data contains conflicting entity

client:

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

server:

HTTP 409 //as in option1, since no CREATE took place
{"id": 1, "name":"bob"} //existing user returned
Nikita
  • 6,019
  • 8
  • 45
  • 54

4 Answers4

22

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

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.

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.

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:

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.

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

Community
  • 1
  • 1
Eric Stein
  • 13,209
  • 3
  • 37
  • 52
  • 1
    very helpful, @Eric Stein. clarification - in the above approach what happens when another process creates 'bob' after the initial GET but before the POST? ie what's the response to POST in that case - a 200 with (now) existing user in body? – Nikita Mar 12 '14 at 14:50
  • @Nikita In that case, I would expect the POST to return a 403. 409 is no good according to the spec: "This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request." Note that there's a lot of arguing about the proper response code in this situation, so you should Google for a more detailed understanding of the issue. – Eric Stein Mar 12 '14 at 14:59
2

I am using a version of option 2. I return 201 when the resource is created, and 303 ("see other") when it is merely retrieved. I chose to do this, in part, because get_or_create doesn't seem to be a common REST idiom, and 303 is a slightly unusual response code.

dbn
  • 13,144
  • 3
  • 60
  • 86
1

I would go with Option 2 for two reasons:

First, HTTP response code, 2xx (e.g. 200 nd 201) refers to a successful operation unlike 4xx. So in both cases when find or create occurs you have a successful operation.

Second, Option 1 doubles the number of requests to the server which can be a performance hit for heavy load.

iTech
  • 18,192
  • 4
  • 57
  • 80
  • that option is indeed less chatty. however, what if we had another use-case - user creation. in that case we would not want to silently return an existing record when attempting to create a new one. If we go with option 2 here, does that mean that another endpoint will be needed (won't that break REST's conventions?); or will client have to interpret HTTP 200 (vs 201) as error in the register-user case? – Nikita Mar 12 '14 at 13:59
  • @Nikita if you choose option 2, then yes, the client will need to look at the response status to determine whether or not the user was created. – Eric Stein Mar 12 '14 at 14:27
0

I believe a GET request which either:

  • returns an existing record; or
  • creates a new record and returns it

is the most efficient approach as discussed in my answer here: Creating user record / profile for first time sign in

It is irrelevant that the server needs to create the record before returning it in the response as explained by @Cormac Mulhall and @Blake Mitchell in REST Lazy Reference Create GET or POST?

This is also explained in Section 9.1.1 of the HTTP specification:

Naturally, it is not possible to ensure that the server does not generate side-effects as a result of performing a GET request; in fact, some dynamic resources consider that a feature. The important distinction here is that the user did not request the side-effects, so therefore cannot be held accountable for them.

Community
  • 1
  • 1
ThierryMichel
  • 487
  • 1
  • 5
  • 20