9

According to the HTTP 1.1. spec:

If the Request-URI does not point to an existing resource, and that URI is capable of being defined as a new resource by the requesting user agent, the origin server can create the resource with that URI.

So in other words, PUT can be used to create & update. More specifically, if I do a PUT request e.g.

PUT /users/1

and that user does not exist, I would expect the result of this request to create a user with this ID. However, how would this work if your backend is using an auto-increment key? Would it be a case of simply ignoring it if it's not feasible (e.g. auto-increment is at 6 and I request 10) & creating if it is possible (e.g. request 7)?

From the snippet I have extracted above it does appear to give you this flexibility, just looking for some clarification.

2 Answers 2

10

I'd suggest that you use POST, not PUT, for an auto-increment key, or do not use the auto-increment key in the resource ID.

If you use POST, then you'd POST to /users rather than to /users/1. The reply might redirect you to /users/1 or whatever the ID is.

If you use PUT, then you might PUT to /users/10292829 where the number is a unique resource key generated on the client. This key can be time-generated, or it can be a hash of time, session ID, and some other factors to guarantee uniqueness of the value across your client audience. The server can then generate its own auto-incremented index, distinct from 10292829 or whatever.

For more on that, see PUT vs POST in REST


Following up. . .

In the case of allowing PUT to /users/XXXXXXX, for all users, you'd end up with two distinct unique keys that refer to the same resource. (10292829 and 1 might refer to the same user). You'd need to decide how to allow the use of each of these different keys in a REST-style URL. Because of the need to reconcile the use of these two distinct ids, I'd prefer to use the first option, POSTing to /users and getting a unique REST url of the created resource in the response.

I just re-read the relevant section of RFC 2616, and saw a return code specifically designed for this in REST applications:

10.2.2 201 Created

The request has been fulfilled and resulted in a new resource being created. The newly created resource can be referenced by the URI(s) returned in the entity of the response, with the most specific URI for the resource given by a Location header field. The response SHOULD include an entity containing a list of resource characteristics and location(s) from which the user or user agent can choose the one most appropriate. The entity format is specified by the media type given in the Content-Type header field. The origin server MUST create the resource before returning the 201 status code. If the action cannot be carried out immediately, the server SHOULD respond with 202 (Accepted) response instead.

So, the RESTful way to go is to POST to /users and return a 201 Created, with a Location: header specifying /users/1.

4
  • My REST API currently supports POST but I want to also support PUT to allow updates. So to avoid the complication of passing unique IDs from the client side should PUT simply return a 404 if the resource doesn't exist rather than attempting to create it? Would this still be considered RESTful?
    – James
    Mar 27, 2012 at 8:11
  • Yes, PUT is designed for updates. If the URI to which the PUT is sent does not refer to an available resource, then a 404 is a reasonable thing to return. If it's REST/JSON, you can include an error message in json format in the message body of the response. {"error":"resource does not exist."}. But really, sending information in the message body is appropriate only if it adds to the information that the status code conveys. If "Does not exist" is the message, then 404 is sufficient, and no message body is necessary.
    – Cheeso
    Mar 27, 2012 at 14:28
  • Cool, so really with PUT you have the choice of whether you want to create or not (which is what I was really looking for clarification on). In think in my scenario then PUT will be purely used for updating (if the resource exists). Thanks!
    – James
    Mar 27, 2012 at 15:10
  • yeah, I think the spec is somewhat open on exactly how PUT ought to be used. But in practice, I try to design a model that is as simple as possible. For me, using a PUT for updates, specifying an existing resource URL, is what makes intuitive sense; using POST for creates, specifying the URL to a resource factory or resource manager, and the 201 Created response, makes sense.
    – Cheeso
    Mar 27, 2012 at 15:26
-1

You should be using POST to create resources while the PUT should only be used for updating. Actually REST semantics forces you to do so.

1
  • 1
    According to the spec, PUT can be used to create resources in the scenario where the resource at the specified URI doesn't exist... this is the dilemma.
    – James
    Mar 27, 2012 at 7:56

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.