'Best' practice for restful POST response

Question

So nothing new here I am just trying to get some clarification and cannot seem to find any in other posts.

I am creating a new resource restulfully, say:

/books (POST)

with a body:

{
  title: 'The Lion, the Witch and the Wardrobe',
  author: 'C. S. Lewis'
}

I know that I should return a 201 (Created) with a Location header of the new resource:

Location: /books/12345

The question I cannot seem to answer for myself is what should the server return in the body.

I have often done this type of response:

{
  id: 12345,
  title: 'The Lion, the Witch and the Wardrobe',
  author: 'C. S. Lewis'
}

I have done this for a couple reasons:

1. I have written api for front end frameworks like angularjs. In my particular case I am using angular resources and I often need just the id for the resource to locate it. If I did not return the id in the response body I would need to parse it out of the Location header.
2. In a GET of all books I usually return the entire object not just the id. In this sense my client code does not have to differentiate where to get the id from (location header or body).

Now I know I am really in the grey area here, but most people are saying that returning the entire resource is 'bad' practice. But what if the server changes/adds information to the resource. It definitely adds the id, but might also add other things like a timestamp. In the case that I do not return the entire resource, is it really better to do a POST, return the id, then have the client perform a GET to get the new resource.

Frightened

I personally prefer empty body for POST responses. Shouldn't RESTful Location header value be an URI (unique resource identifier)? So maybe should you use it as an ID and not parse it to figure out a server internal ID. IMO, RESTful API consumers should navigate using hyperlinks provided and not build path, guessing where a particular server locates resources... And after all, doesn't the client already know the state of the resource it just created ? repeating it seams a waste of network resources. – Teem

For Create/Insert, Status 201 - CREATED, Header Location →localhost:8080/employees/1 (See: here) – Moderato

Answer 1

Returning the whole object on an update would not seem very relevant, but I can hardly see why returning the whole object when it is created would be a bad practice in a normal use case. This would be useful at least to get the ID easily and to get the timestamps when relevant. This is actually the default behavior got when scaffolding with Rails.

I really do not see any advantage to returning only the ID and doing a GET request after, to get the data you could have got with your initial POST.

Anyway as long as your API is consistent I think that you should choose the pattern that fits your needs the best. There is not any correct way of how to build a REST API, imo.

Unaccustomed

I know this is old, but I can give a convincing argument for using a GET after your POST. In the http/1.1 spec any historical tool can ignore the cache settings passed back from your GET response... so if your user uses the back button in the browser to return to this page after you updated it with the POST it can use stale cached data from the original GET. So if you reuse the GET then you can update the cache and get a better snapshot of how the page looked when they left... – Capel

@Capel If the API is designed to be used by apps also, then your argument for making two requests doesn't hold. There, you usually cache the data by keeping objects of a model type in memory – which is typically done with the response for POST requests. And regarding browsers, the response on a POST request doesn't really hurt so long as there still is a GET api endpoint. – Longerich

I subscribe what Daniel states here. Even if you check mature frameworks like Spring Data, they always return the whole object after persisting it. I think it's a good practice, as in you client you will save a server roundtrip to get the same information – Weeper

Answer 2

Returning the new object fits with the REST principle of "Uniform Interface - Manipulation of resources through representations." The complete object is the representation of the new state of the object that was created.

There is a really excellent reference for API design, here: Best Practices for Designing a Pragmatic RESTful API

It includes an answer to your question here: Updates & creation should return a resource representation

It says:

To prevent an API consumer from having to hit the API again for an updated representation, have the API return the updated (or created) representation as part of the response.

Seems nicely pragmatic to me and it fits in with that REST principle I mentioned above.

Adenocarcinoma

how about returning the entire set of relevant objects? this way, possible sorting can be done server-side, and it eases front-end implementation – Ame

But these best practices aren't best. The author statet that HATEOAS, which is important same as other principles, must not be used because "it is not ready". HATEOAS never will be "ready", because all RESTful principles are just architectural design principles, not specific implementation. The quoted reference is about author's vision about RESTful API, which isn't RESTful at all because of dropping HATEOAS. That's why this is not the best reference :) – Howell

@Howell - you will note that the original question had quotes around 'Best', I guess because there is a great deal of opinion in this area. The reference I pointed to is something I've found to be practical. If you have a better reference please share it. I'm always open to learning more. – Adenocarcinoma

@Adenocarcinoma An implementation is a different thing that architectural design priciple/pattern. Nobody can expect that HATEOAS will be ready someday, but there is a chance that somebody will create an implementation acceptable by many. Vinay also wrote about mapping http methods to URLs and specific operations (CRUD), stated that versioning by prefixing urls is more pragmatic, wrote that filtering by query parameters is a way to go... it's fine, but all of this has little to do with RESTful architecture. He wrote about some kind of contract. That's fine for HTTP API, but don't call it RESTful. – Howell

@Adenocarcinoma Here are some posts explaining this: - medium.com/@andrea.chiarelli/… - restfulapi.net – Howell

@Adenocarcinoma Nice explanation. But failing to patch or post should also return error message in consumable format. Maybe this needs to be added to your answer... ? More at vinaysahni.com/… – Chetchetah

Answer 3

After a post I like to return something like this:

Response
   .created(URI("/obj/$id"))
   .entity(TheNewObj())
   .build()

Status 201 - CREATED

Header Location - the location of the new object

Entity - the new object

Beetle

Answer 4

The whole REST response thing is a highly opinionated discourse and no best practices exist, but I more and more believe a standard response to each and any rest call might be beneficial for your clients. The RFC7807 does describe such a response. I'm not claiming to have the answer here but just point out it might be something to look into. Reflecting back the content of a request seems superfluous. Just an Ok (200) or created (201) might be sufficient. Nobody currently holds the truth here though it is a matter of common sense.

EDIT: as lostintranslation comments: The server might changed the payload for whatever reason (normalizing, calculations, etc) in which case it does make sense to reflect the current state of the resource in the payload for the client to show to the user.

Militia