Should a RESTful 'PUT' operation return something....

Question

I was wondering what people's opinions are of a RESTful PUT operation that returns nothing (null) in the response body.

system PAUSE · Accepted Answer · 2023-03-16T17:02:29.780

764

The HTTP specification (RFC 2616) has a number of recommendations that are applicable. Here is my interpretation:

HTTP status code 200 OK for a successful PUT of an update to an existing resource. No response body needed. (Per Section 9.6, 204 No Content is even more appropriate.)
HTTP status code 201 Created for a successful PUT of a new resource, with the most specific URI for the new resource returned in the Location header field and any other relevant URIs and metadata of the resource echoed in the response body. (RFC 2616 Section 10.2.2)
HTTP status code 409 Conflict for a PUT that is unsuccessful due to a 3^rd-party modification, with a list of differences between the attempted update and the current resource in the response body. (RFC 2616 Section 10.4.10)
HTTP status code 400 Bad Request for an unsuccessful PUT, with natural-language text (such as English) in the response body that explains why the PUT failed. (RFC 2616 Section 10.4)

Note: RFC 2616 was the latest specification when this answer was written, but the RFC has since been superseded. When referring to any standard, it can be useful to verify that you are using the latest one.

edited Mar 16 '23 at 17:02

answered May 05 '09 at 21:44

system PAUSE

37,082
20
62
59

31

@stian Interesting! That seems pretty presumptuous on the part of Mozilla, since I can find nothing in RFC 2616 (notably sections [10.2 Successful 2xx](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2) and [10.2.1 200 OK](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.1)) that specifically rule out the use of `200` for PUT, DELETE, or any other method. Did I miss something? Such as Mozilla becoming the boss of W3 and the IETF? ;) Or maybe they've just never heard of Postel's Robustness Principle. – system PAUSE Jan 24 '13 at 22:26
58

@stian: That sentence was removed on Feb 3 2013. Probably because someone read about it here. ;) https://developer.mozilla.org/en-US/docs/HTTP/HTTP_response_codes$compare?from=346227&to=351003 – Christian Strempfer Apr 10 '13 at 21:15
7

The semantics of the PUT method is to ignore whatever current state the resource is in, therefore to return a 409 conflict for a PUT that is unsuccessful due to a 3rd party modification only makes sense if the request is conditional. – Pedro Werneck Jun 17 '14 at 19:07
1

@PedroWerneck, if you look at the RFC link, it explains (sorta) the case for a 409 response to PUT. It doesn't say "conditional" but it says "if versioning is being used" which I infer is the same thing. – system PAUSE Jun 24 '14 at 16:03
13

@systemPAUSE Nice answer. One small point: if you are not going to be returning a response body to a successful operation, I would suggest using a 204 exclusively. Some clients (jQuery Ajax, for example) will choke if they are expecting a non-zero length response but don't get it. You can see an example of this [in this question](http://stackoverflow.com/questions/20928929/jquery-ajax-call-executes-error-on-200/20929815). – nick_w Jul 20 '14 at 21:28
RestAPITutorial.com also recommends returning 200 OK for a successful PUT request on an item. http://www.restapitutorial.com/lessons/httpmethods.html – Kris Khaira Dec 26 '14 at 07:21
You might need at least the ID of the newly created resource from the server. Else the client can't know which entity was created. – Tarion Feb 22 '16 at 02:07
@Tarion: The second bullet point of my answer covers exactly how to do that, in a manner consistent with the HTTP spec. – system PAUSE Mar 23 '16 at 22:44
Why would you include in the response the URI for the new resource in the Location header? The client already knows it because he did the POST to that same URI? – BornToCode Jul 28 '16 at 09:57
1

@BornToCode POST which would imply a 'CREATE' would mean a URI without UID of the entity to create. Therefore you wont know the resulting entity, you're only sending what you want to create, but you wont know which UID it will have. That's why you should respond in one way or another with the location (or UID) of the newly created entity. – appleseedexm Oct 17 '16 at 13:09
1

I want to return `{ "status":"ok", "modified":true }` if the resource is updated by the PUT, and `{ "status":"ok", "modified":false }` is the resource was not updated. The latter case is when a subsequent PUT with no change in the request payload results in no change of the specified resource. As PUT is supposed to be idempotent, I don't know if this is even permissible according to the specs. What else can I use to indicate that a PUT operation did not cause an update? I don't want to use a 40x value since that implies an error. – Web User Mar 06 '17 at 21:44
Actually, I would suggest to return the status (like the `version`) of the resource to the client when use put, and then the client needn't to send get request for the resource. – Bruce Mar 29 '17 at 11:55
8

Possibly RFC2616 has been updated since this was answered. No where in 9.6 does it mention `No response body needed` in relation to a 200. In fact the response body is not mentioned at all in relation to a PUT. It only states `If an existing resource is modified, either the 200 (OK) or 204 (No Content) response codes SHOULD be sent to indicate successful completion of the request.` – james Jul 19 '17 at 14:57
1

I'd add HTTP 422 Unprocessable Entity. It helps to distinguish between a "Bad request" (e.g. malformed XML/JSON) and invalid field values – vdboor Apr 19 '18 at 14:19
1

"HTTP status code 400 Bad Request for an unsuccessful PUT," I guess the spec was updated, because it doesn't say this.. or anything about PUT other than situationally using a 409 – Alkanshel Apr 27 '18 at 01:51
This approach could be extended to allow a query parameter analogous to the `RETURNING` clause in the Postgresql flavour of SQL `UPDATE` to indicate whether and what to return. – beldaz Jul 10 '18 at 09:59
@systemPAUSE Postel's Robustness Principle has its criticism though https://en.wikipedia.org/wiki/Robustness_principle#Criticism – Caltor Aug 19 '19 at 13:30
1

Note that: `This document has been superseded. In 2014, RFC2616 was replaced by multiple RFCs (7230-7237). See IETF Documents for more information.` – August Janse Nov 23 '20 at 22:00
2

@AugustJanse How delightful to hear that the standards have progressed! And happier still, if in the meantime others were encouraged by my answer here to go read them. However, I'm not confident I can edit this answer at this point, or should. In keeping with the Q&A format here, perhaps creating and upvoting a separate answer based on more recent specs would be best? – system PAUSE Feb 07 '21 at 00:35
1

@systemPAUSE If you're asking me, it wouldn't hurt to edit the question to leave a note that the RFC has been superseded, as suggested in [this meta answer](https://meta.stackoverflow.com/a/268382/1729441). As you say, the more recent specs may be more suited for a new answer. – August Janse Feb 07 '21 at 02:08

score 223 · Answer 2 · answered Apr 28 '09 at 14:13

223

As opposed to most of the answers here, I actually think that PUT should return the updated resource (in addition to the HTTP code of course).

The reason why you would want to return the resource as a response for PUT operation is because when you send a resource representation to the server, the server can also apply some processing to this resource, so the client would like to know how does this resource look like after the request completed successfully. (otherwise it will have to issue another GET request).

answered Apr 28 '09 at 14:13

LiorH

18,524
17
70
98

29

@Raedwald sure it is. REST doesn't require that the *entire* resource be updated on a PUT, although it's generally recommended. Some fields might not make sense to update -- created date or last modified date, for example, should probably not be included in the PUT body, but would likely be changed as a result of the PUT. That having been said, I do not agree with LiorH that a PUT should result in a return of the resource; I would require a GET after the PUT to obtain the updated resource. – Randolpho Oct 08 '12 at 21:16
25

@Randolpho _REST doesn't require that the entire resource be updated on a PUT_ shouldn't this be the case of a PATCH? – Marco Ciambrone Oct 14 '13 at 08:37
16

@MarcoCiambrone Yes, I agree and I recant my previous comment. I've changed my tune on REST and PUT -- PUT should always be idempotent and should never be used for a partial update. POST is the only alternative unless PATCH is supported, in which case PATCH may be a good alternative. PATCH is a new verb, however, and may not be supported by some server-side frameworks. – Randolpho Oct 14 '13 at 20:15
Another issue is that PATCH doesn't define *how* a partial update is done, only that the body carries a "description of changes", meaning that it's not as discoverable as might be warranted for a good RESTful API. Of course, this is the same issue you'd run into with a POST for partial update. – Randolpho Oct 14 '13 at 20:16
@Randolpho: In case of the PATCH method, I believe it is not only about server-side frameworks, as you want your service to be accessible from different clients that might not be able to include support for PATCH as well. – Hermes Dec 11 '13 at 17:28
PUT vs PATCH is a side issue. A server may require a full object from the client, but REST only requires of the server that the request is idempotent. In response to a PUT, the server could well do other processing (database triggers, etc), and the resulting resource (and/or other resources) might not be exactly what was PUT. – shaunc Dec 31 '14 at 09:46
It is not required to return the entire resource in put method. Service should return the location of modified/new resource in the 'Location' header field. – Farshid Saberi Dec 24 '15 at 21:29
Returning updated resource after PATCH/PUT also simplifies your request specs. – demisx Jun 21 '16 at 16:14
Best answer here imo, the client shouldn't need the "secret" knowledge that the server has modified the entity and needs to make a (wasteful) GET to keep them in sync – Dominic Oct 31 '16 at 08:58
2

The answer was written well before rfc7231, but [section 4.3.4](https://tools.ietf.org/html/rfc7231#section-4.3.4) makes it clear "The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload" – aaaaaa Aug 13 '17 at 00:32
I think the comments here have mostly been a detour. All in all, I don't see why returning a modified object violates RESTful or "HTTP RESTful", regardless of whether the object was fully modified, or partially modified. – Leo Lei Jan 10 '18 at 03:08
5

What if the updated object is large? Seems wasteful to return a lot of data that isn't likely to be used. – beldaz Jul 10 '18 at 09:21
@beldaz you are absolutely right. This is why everyone should take this answer with a grain of salt: If you go down path of returning a value here the 's' (single-responsibility) in 'solid' is immediately violated. The action should simply update the resource but it should never make assumptions about what the client needs after the update and for that matter it should not return anything in the body (as a general rule of thumb 'don't read your writes'). If the client needs the updated resource it can make a separate call. It's the responsibility of the caching layer to ensure performance! – XDS Feb 05 '20 at 10:47
@XDS Care to explain why is there such rule that 'dont read your writes', can explain more why should not we return the updated data in PUT response? – tnkh Aug 06 '20 at 07:25
Read up on the life-saving 'SOLID' principles: It's the letter 'S' (aka "single responsibility"). There are excellent tutorials out there explaining the logic behind all of the 5 principles. I would recommend an excellent video-tutorial or two but SO rules prohibit me from doing so :( Feel free to look them up – XDS Aug 06 '20 at 08:35
1

@Raedwald Re: _"the server can also apply some processing to this resource": I'm new this this. Is that really RESTful?_. YES. 2014's RFC 7231 (one of RFCs that obsolete the 1999's RFC 2616) mentions [here](https://tools.ietf.org/html/rfc7231#section-4.3.4) that server can cause `"transformation applied to the body"`. There's even a mechanism for client to `"allows a user agent to know when the representation body it has in memory remains current"`, i.e. the server `"MUST NOT send ... an `ETag` or `Last-Modified` ... unless the request's representation was saved without any transformation"`. – Slawomir Brzezinski Oct 26 '20 at 08:03
@aaaaaa Re: _"The answer was written well before rfc7231, but section 4.3.4 makes it clear "The PUT method requests that the state of the target resource be created or replaced with the state defined by the representation enclosed in the request message payload"_. NOT QUITE. RFC 7231 actually recognizes [here](https://tools.ietf.org/html/rfc7231#section-4.3.4) that PUT can include `"transformation applied to the body"` (even has response headers behavior that `"allows a user agent to know when the representation body it has in memory remains current"`). – Slawomir Brzezinski Oct 26 '20 at 08:13
On the whole @LiorH answer's _"PUT should return the updated resource (in addition to the HTTP code of course)"_. As much as there is nothing wrong with doing it (see my comments with `transformation applied to the body`) **please fix the answer to not say 'should'**, as this is incorrect. What can be said is that returning them can help there when server causes `transformation applied to the body` or the response was `subject to dynamic processing by the origin server, before any subsequent GET is received` (As per the 2014's RFC 7231). – Slawomir Brzezinski Oct 26 '20 at 08:57
You took that quote out of context. That portion is not describing the semantics of the payload but giving a general description of what it's referring to. – aaaaaa Oct 26 '20 at 16:54
@aaaaaa I see that the OP answer is from 2009, while RFC 7231 is from 2014, so you are right on that incidental fact that 'The answer was written well before 7231'. But that doesn't change the fact that the answer suggests doing something that is often useful even now and perfectly valid as per 7231, so 7231 did not invalidate the OP suggestion (although the OP should not say everyone 'should' do it, but rather only where it makes sense, and only together with omitting the Last-Modified and ETag, and without expectations that any intermediary cache will cache the response). – Slawomir Brzezinski Oct 27 '20 at 21:10

score 9 · Answer 3 · answered Feb 05 '19 at 20:30

If the backend of the REST API is a SQL relational database, then

you should have RowVersion in every record that can be updated (to avoid the lost update problem)
you should always return a new copy of the record after PUT (to get the new RowVersion).

If you don't care about lost updates, or if you want to force your clients to do a GET immediately after a PUT, then don't return anything from PUT.

score 8 · Answer 4 · answered Dec 31 '14 at 10:00

I think it is possible for the server to return content in response to a PUT. If you are using a response envelop format that allows for sideloaded data (such as the format consumed by ember-data), then you can also include other objects that may have been modified via database triggers, etc. (Sideloaded data is explicitly to reduce # of requests, and this seems like a fine place to optimize.)

If I just accept the PUT and have nothing to report back, I use status code 204 with no body. If I have something to report, I use status code 200, and include a body.

Pravind Kumar · Answer 5 · 2021-07-24T06:25:54.203

5

Http method "PUT" may have different Http status as per execution status on passed request-URI. The Below table may help to understand -

edited Jul 24 '21 at 06:25

answered Jul 24 '21 at 05:55

Pravind Kumar

809
1
11
10

score 4 · Answer 6 · answered Apr 28 '09 at 13:13

4

The HTTP/1.1 spec (section 9.6) discusses the appropriate response/error codes. However it doesn't address the response content.

What would you expect ? A simple HTTP response code (200 etc.) seems straightforward and unambiguous to me.

answered Apr 28 '09 at 13:13

Brian Agnew

268,207
37
334
440

Yes, but what if you want to check whether the inserted data into db after a PUT or POST really represents the true data you want. It would be better if the HTTP can send back the body of the response. – tnkh Sep 26 '19 at 08:50
2

@tnkh what you suggest is downright a horrible idea. Make a separate GET call after a successful update to achieve what you want. In order to ensure performance introduce a caching layer if you are facing issues in this department. We can't solve these issues by messing around with 'everything goes' kind of logic. Don't mess around with 'solid' and basic programming principles which should be common sense in the year 2020. It's a disgrace! – XDS Feb 05 '20 at 10:50
1

@XDS I acknowledge your first part of the comment. But cant stop to roll my eyes after that. Hilarious comment – tnkh Feb 06 '20 at 00:10
1

Thanks on elaborating on why you find it hilarious though. – XDS Feb 06 '20 at 08:29
1

@XDS "introduce a caching layer if you are facing issues in this department". That's an interesting idea, and shows why it's useful if you can rely on the server return the updated resource - You can't cache after a PUT because you don't know what the resource should look like. If the resource comes back on the response, you can cache that, otherwise you have to do the GET and cache the output of that, but reducing the effect of the GETs is exactly why you suggested introducing the caching layer in the first place. – kybernetikos Sep 09 '22 at 14:14

score 1 · Answer 7 · answered Jan 03 '23 at 22:17

I agree with the most voted answers above, but I would like to elaborate more on this.

REST is not a standard, therefore everyone could create and document it's own API as long as it fits the purpose and it is well documented, agreed and understood by the developers and consumers. What really matter is that the URLs identifies the exposed resources. I have been working with Http Rest APIs for years and I want to share what generally I use as standard approach, not because it's perfect, or "the rules of conduct", just because I found it easy to work with and explain to others.

Note that I am not mentioning hypermedia as this goes far beyond the purpose of the answer and I rather leave it out of scope, but if interested a good reading can be found in the OData specification.

Create
---------------------------------------------------------------------
Success - 201 Created - Return created object
Failure - 400 Invalid request - Return details about the failure
Async fire and forget operation - 202 Accepted - Optionally return url for polling status

Update
---------------------------------------------------------------------
Success - 200 Ok - Return the updated object
Success - 204 NoContent
Failure - 404 NotFound - The targeted entity identifier does not exist
Failure - 400 Invalid request - Return details about the failure
Async fire and forget operation - 202 Accepted - Optionally return url for polling status

Patch
---------------------------------------------------------------------
Success - 200 Ok - Return the patched object
Success - 204 NoContent
Failure - 404 NotFound - The targeted entity identifier does not exist
Failure - 400 Invalid request - Return details about the failure
Async fire and forget operation - 202 Accepted - Optionally return url for polling status

Delete
---------------------------------------------------------------------
Success - 200 Ok - No content
Success - 200 Ok - When element attempting to be deleted does not exist
Async fire and forget operation - 202 Accepted - Optionally return url for polling status

Get
---------------------------------------------------------------------
Success - 200 Ok - With the list of resulting entities matching the search criteria
Success - 200 Ok - With an empty array

Get specific
---------------------------------------------------------------------
Success - 200 Ok - The entity matching the identifier specified is returned as content
Failure - 404 NotFound - No content

Action
---------------------------------------------------------------------
Success - 200 Ok - Return content where appropriate
Success - 204 NoContent
Failure - 400 - Return details about the failure
Async fire and forget operation - 202 Accepted - Optionally return url for polling status

Generic results
---------------------------------------------------------------------
Authorization error 401 Unauthorized
Authentication error 403 Forbidden
For methods not supported 405
Generic server error 500

score 0 · Answer 8 · answered Jul 31 '12 at 18:37

0

Http response code of 201 for "Created" along with a "Location" header to point to where the client can find the newly created resource.

answered Jul 31 '12 at 18:37

dc360

215
3
3

8

PUT objects aren't (or shouldn't be) newly created resources – kdazzle Nov 01 '13 at 17:44
12

@kdazzle PUT can certainly be a newly created resource, and often would be. http://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.6 – Charlie Schliesser Jun 18 '14 at 16:48
@CharlieS Agreed. There is nothing wrong with this answer at all. In fact, this answer restates point 2 of the accepted answer. – nick_w Jul 20 '14 at 21:20
The PUT request should always know the location, even if the resource is new. If the location isn't known, then the request should have been a POST. This answer isn't RESTful, and shows incorrect usage of PUT verb. – user1751825 Jan 31 '16 at 13:50
3

Just to explain my comment a bit better. PUT means, put this item at this specific location, replacing what's currently there (if applicable). – user1751825 Feb 02 '16 at 04:02
3

Right, "replacing what's currently there" is the key phrase. It should already exist and it is being replaced. PUT should not be for creating new resources. – Kevin M May 01 '17 at 14:39
4

@KevinM As in the latest [RFC doc rfc7231](https://tools.ietf.org/html/rfc7231#section-4.3.4), it says that resources can be created: "The PUT method requests that the state of the target resource be **created** or replaced [...]" and the reason you're thinking PUT cannot create new resource is because you don't necessarily know the location of the new resource. But if you know its location/identifier, it **can be created** if it's not yet there. – Leo Lei Jan 10 '18 at 03:14

score 0 · Answer 9 · answered Mar 29 '17 at 12:32

I used RESTful API in my services, and here is my opinion: First we must get to a common view： PUT is used to update an resource not create or get.

I defined resources with: Stateless resource and Stateful resource:

Stateless resources For these resources, just return the HttpCode with empty body, it's enough.
Stateful resources For example: the resource's version. For this kind of resources, you must provide the version when you want to change it, so return the full resource or return the version to the client, so the client need't to send a get request after the update action.

But, for a service or system, keep it simple, clearly, easy to use and maintain is the most important thing.

"PUT is used to update an resource not create or get." - that's not true nor common. By spec, PUT can create the resource. Clear = following the commonly known spec. — Imre Pühvel, Oct 26 '18 at 06:40

score 0 · Answer 10 · answered Aug 23 '23 at 07:52

RFC7231 does not specify the response body of a PUT method. Do whatever works for you. For example,

Empty (use status No Content to avoid some problems).
The updated resource representation.
Anything.

HTTP does not define exactly how a PUT method affects the state of an origin server beyond what can be expressed by the intent of the user agent request and the semantics of the origin server response.

If the target resource does not have a current representation and the PUT successfully creates one, then the origin server MUST inform the user agent by sending a 201 (Created) response.

Responses to the PUT method are not cacheable.

Jason S · Answer 11 · 2009-04-28T13:27:47.623

-4

seems ok... though I'd think a rudimentary indication of success/failure/time posted/# bytes received/etc. would be preferable.

edit: I was thinking along the lines of data integrity and/or record-keeping; metadata such as an MD5 hash or timestamp for time received may be helpful for large datafiles.

edited Apr 28 '09 at 13:27

answered Apr 28 '09 at 13:10

Jason S

184,598
164
608
970

2

How about 200 OK in the status response header? Do think thats enought to say, "Worked fine thanks?" – AnthonyWJones Apr 28 '09 at 13:11
the response header would contain the status code, and yes we are talking about HTTP at this point :) – AwkwardCoder Apr 28 '09 at 13:12

score -4 · Answer 12 · answered Apr 28 '09 at 13:13

-4

Just as an empty Request body is in keeping with the original purpose of a GET request and empty response body is in keeping with the original purpose of a PUT request.

answered Apr 28 '09 at 13:13

AnthonyWJones

187,081
35
232
306

score -5 · Answer 13 · answered Apr 28 '09 at 13:10

-5

Ideally it would return a success/fail response.

answered Apr 28 '09 at 13:10

cgp

41,026
12
101
131

13

Not in the response body, though. The HTTP status code is the place for that. Maybe if there's an error some extended error information could be returned in the response bidy – The Archetypal Paul Apr 28 '09 at 13:13

score -5 · Answer 14 · answered Apr 28 '09 at 13:15

-5

There's a difference between the header and body of a HTTP response. PUT should never return a body, but must return a response code in the header. Just choose 200 if it was successful, and 4xx if not. There is no such thing as a null return code. Why do you want to do this?

answered Apr 28 '09 at 13:15

AlexanderJohannesen

2,028
2
13
26

There's no such reference on RFC about the statement "PUT should never return a body". Furthermore, if you choose to return 200, this means you probably do return a body (unless you choose for 204) – Fabrizio Stellato Mar 17 '21 at 14:37

Should a RESTful 'PUT' operation return something....

14 Answers14

Linked