160

  1. According to the "REST ideology" what should be in the response body for a PUT/POST/DELETE requests?

  2. What about return codes? Is HTTP_OK enough?

  3. What is the reason for such conventions, if any?

I've found a good post describing POST/PUT differences: POST vs PUT But it still doesn't answer my question.

Sam
  • 7,252
  • 16
  • 46
  • 65
tuxSlayer
  • 2,804
  • 2
  • 20
  • 24

5 Answers5

134

Forgive the flippancy, but if you are doing REST over HTTP then RFC7231 describes exactly what behaviour is expected from GET, PUT, POST and DELETE.

Update (Jul 3 '14):
The HTTP spec intentionally does not define what is returned from POST or DELETE. The spec only defines what needs to be defined. The rest is left up to the implementer to choose.

Community
  • 1
  • 1
Darrel Miller
  • 139,164
  • 32
  • 194
  • 243
  • Yeah, I've missed this fact. Thank you! This looks much more logical than to "invent" some new meaning for each http "method" and surely more logical than mapping to SQL operations. – tuxSlayer Nov 25 '10 at 14:38
  • 9
    @tuxslayer I'm glad you didn't think I was just trying to be snarky. Many people seem to think REST adds addition requirements on top of the HTTP methods. However, that is not the case. There are additional constraints but they do not really impact the behaviour of the HTTP methods. RFC2616 is definitely the guide to follow. – Darrel Miller Nov 25 '10 at 16:36
  • 4
    I appreciate the link. :) It made me stop and think about the tool I'm using. After reading your post, and the RFC, I found myself referring to the RFC the rest of the night. It's helped me think of the process as an HTTP process first, and a rest process second. Much appreciated. – Perry Tew Aug 05 '12 at 00:57
  • 4
    @PerryTew Now you can go here http://tools.ietf.org/wg/httpbis/ and see the currently being revised version of the HTTP spec. Enjoy! – Darrel Miller Aug 05 '12 at 01:49
  • 12
    Maybe I just need more sleep, but I can't seem to find the exact information that the OP asked for within the RFC. What should the body be for a POST or DELETE response? – Cam Jackson Jul 03 '14 at 12:21
  • 1
    @CamJackson That's partly because the HTTP spec intentionally does not define what is returned from POST or DELETE. The spec only defines what needs to be defined. The rest is left up to the implementer to choose. The new spec has a bit more discussion though http://tools.ietf.org/html/rfc7231 – Darrel Miller Jul 03 '14 at 12:50
  • 10
    Well, that's about as clear as mud. Perhaps some more information in the answer would be helpful. Especially, when that link is dead. – Doug Molineux Aug 26 '14 at 16:44
  • @DougMolineux Hmm, the link works for me, but anyway. Fortunately, several of the world's experts on HTTP spent the last 5 years re-writing big chunks of the HTTP spec to make it clearer. Here are the updated HTTP method definitions http://tools.ietf.org/html/rfc7231#section-4.3 – Darrel Miller Aug 27 '14 at 13:07
  • @DarrelMiller Your Jul 3 '14 12:50 comment should be the answer. I've added it to the answer. – Ganesh Jadhav May 21 '19 at 11:00
  • It seems to me the OP specifically asked about REST which by convention runs over http and has prescriptions for how it is used. REST is a convention, and I don't really see how providing a protocol specification can be a definitive answer to a question regarding a convention that uses it. – Howard Swope Aug 08 '22 at 16:19
  • @HowardSwope REST is an architectural style defined independently of HTTP. That's why section 6.3 of the dissertation is called "REST applied to HTTP". HTTP/1.1 is an implementation of the REST architectural style. I agree that the way the term REST is used today makes it seem like the opposite, but it is just plain wrong. – Darrel Miller Aug 13 '22 at 14:46
26

Overall, the conventions are “think like you're just delivering web pages”.

For a PUT, I'd return the same view that you'd get if you did a GET immediately after; that would result in a 200 (well, assuming the rendering succeeds of course). For a POST, I'd do a redirect to the resource created (assuming you're doing a creation operation; if not, just return the results); the code for a successful create is a 201, which is really the only HTTP code for a redirect that isn't in the 300 range.

I've never been happy about what a DELETE should return (my code currently produces an HTTP 204 and an empty body in this case).

Donal Fellows
  • 133,037
  • 18
  • 149
  • 215
  • 1
    Having the `PUT` request return the next page seems like a bad practice, since refreshing on the resulting page will cause the request to execute again. Instead, to me, it makes sense to do a redirect, assuming you're dealing with synchronous requests. – lobati Jun 16 '15 at 16:03
  • 1
    @lobati I think it's important to note that sending multiple identical PUT requests, should have precisely the same result as sending only one of the same PUT requests. Perhaps the issue you raise is now less important given the above? – Iain Aug 26 '15 at 18:48
  • 3
    @Iain not really. The problem is, if something else updates the record later, you wouldn't want to have it send another `PUT` request causing the data to be reverted. For example, if two people are referencing the same page, one makes an update, then the other makes an update, if the first person refreshes to see the result, it would end up actually causing things to be reverted to before the second person made their changes. – lobati Aug 26 '15 at 22:05
  • "Think like website" is perfect, thus a delete may respond with some likely next actions, which depends on the "story" around why you'd be deleting a resource. This could at least be a link to take the agent back to some logical starting place of actions, or even a redirect to a status resource that shows the impact of the delete (order total) and contains further links. – Luke Puplett Jul 17 '19 at 09:09
3

Creating a resource is generally mapped to POST, and that should return the location of the new resource; for example, in a Rails scaffold a CREATE will redirect to the SHOW for the newly created resource. The same approach might make sense for updating (PUT), but that's less of a convention; an update need only indicate success. A delete probably only needs to indicate success as well; if you wanted to redirect, returning the LIST of resources probably makes the most sense.

Success can be indicated by HTTP_OK, yes.

The only hard-and-fast rule in what I've said above is that a CREATE should return the location of the new resource. That seems like a no-brainer to me; it makes perfect sense that the client will need to be able to access the new item.

Jacob Mattison
  • 50,258
  • 9
  • 107
  • 126
  • 2
    You've actually mixed up PUT and POST. POST is used for creating, PUT is used for updating (and creating). It's also worthwhile to note that PUT should be idempotent whereas POST is not. – Stevie Jan 18 '13 at 12:19
  • An idempotent command should work properly however many times you run it. So you should be able to do the same PUT multiple times to apply the same "update" without any negative side effects. – Jacob Mattison Jan 28 '19 at 19:37
  • Actually PUT can can be used for an "upsert", when you have a "natural" key. As long as multiple puts don't matter to the result, you are good. Post can be thought of as "out of band"; we're talking api commands, or information that begins or ends processes, or objects that are not representations on the servers you are posting to, or not idempotent operations or documents. It can also request data that might be dynamic in nature. Post can do anything, but to take advantage of caching infrastructure it should be limited to the stuff the other verbs weren't meant to do. – Gerard ONeill May 18 '23 at 21:09
3

I like Alfonso Tienda responce from HTTP status code for update and delete?

Here are some Tips:

DELETE

  • 200 (if you want send some additional data in the Response) or 204 (recommended).

  • 202 Operation deleted has not been committed yet.

  • If there's nothing to delete, use 204 or 404 (DELETE operation is idempotent, delete an already deleted item is operation successful, so you can return 204, but it's true that idempotent doesn't necessarily imply the same response)

Other errors:

  • 400 Bad Request (Malformed syntax or a bad query is strange but possible).
  • 401 Unauthorized Authentication failure
  • 403 Forbidden: Authorization failure or invalid Application ID.
  • 405 Not Allowed. Sure.
  • 409 Resource Conflict can be possible in complex systems.
  • And 501, 502 in case of errors.

PUT

If you're updating an element of a collection

  • 200/204 with the same reasons as DELETE above.
  • 202 if the operation has not been commited yet.

The referenced element doesn't exists:

  • PUT can be 201 (if you created the element because that is your behaviour)

  • 404 If you don't want to create elements via PUT.

  • 400 Bad Request (Malformed syntax or a bad query more common than in case of DELETE).

  • 401 Unauthorized

  • 403 Forbidden: Authentication failure or invalid Application ID.

  • 405 Not Allowed. Sure.

  • 409 Resource Conflict can be possible in complex systems, as in DELETE.

  • 422 Unprocessable entity It helps to distinguish between a "Bad request" (e.g. malformed XML/JSON) and invalid field values

  • And 501, 502 in case of errors.

Community
  • 1
  • 1
Ryabchenko Alexander
  • 10,057
  • 7
  • 56
  • 88
1

By the RFC7231 it does not matter and may be empty

How we implement json api standard based solution in the project:

post/put: outputs object attributes as in get (field filter/relations applies the same)

delete: data only contains null (for its a representation of missing object)

status for standard delete: 200

Marius Gri
  • 59
  • 3