0

This is really a question about "best" or "practical" practices, and would be interested if anyone else has had a similar need as myself, and how they handled it.

I have a REST(ish) API that we have developed to "bolt onto" the front of an existing legacy system. I use this "REST" API to enable both third party, and our own upcoming Mobile applications to interact with our existing system.

I take a pragmatic approach (thats why I use the term RESTish), where I follow the REST guidelines as best possible, but don't let it get in the way if I do need to stray from them to suite our business needs (and the fact that it is being bolted onto the front of a legacy system). If I do something not "pure REST", then so be it.

When creating POST requests, it seems common to return the whole record (object) in the response to the POST. I currently don't do this, as I really don't see the value in our use cases, but have been told that perhaps I should be. Also, in the few cases whee I will use a batch POST (many records, eg an offline client app coming online), returning every single object again included in the batch (especially for a Mobile client app), just seems wasteful to me.

Other places, I have also seen mentioned, that perhap you just return a "link" to the new object (ie URL to the "created" object), or perhaps some known "key" or Id. Our problem is, the way the system works the JSON payload data "shape" used in the REST request is lost, as the request is passed onto the legacy system (in our case via RPC style calls), so if I wanted to pass back the original JSON objects, I'd need to perhaps serialise it to a string, and pass it all the way through so I can add it to the REST front end service once it comes back from the legacy system. I really would prefer NOT to do this.

My question is, is it really that bad NOT to return a created resource (or sometimes just updated resource) in the same format it is POSTED? IS it just as valid to return some sort of Id or key?

Thanks in advance for any suggestion here!

  • 1
    It might interest 202 Accepted. The representation sent with this response ought to describe the request's current status and point to (or embed) a status monitor that can provide the user with an estimate of when the request will be fulfilled Whether The representation sent with this response ought to describe the request's current status and point to (or embed) a status monitor that can provide the user with an estimate of when the request will be fulfilled means an id, a URL or a whole resource representation is up to you. – Laiv Nov 7 '18 at 7:39
  • 1
    @laiv yes that is a good point that I recently stumbled upon myself. My posts do exactly that, validated and then queued to be async sent to the database server, so a 202 would have been better here. – peterc Nov 7 '18 at 22:32
  • 1
    And you still can send back to client a response body. The one that best suites your needs. – Laiv Nov 7 '18 at 22:39
4

is it really that bad NOT to return a created resource ... in the same format it is POSTED?

HTTP actually gives you a lot of freedom in how you respond to messages.

For example, the section that specifies the 200 OK response code describes the kind of representations you might see in the response body.

POST a representation of the status of, or results obtained from, the action;

"representation of the status of the action could just be

Congratulations! we created a resource.

There's nothing in the semantics of the operation that says you must return a representation of the resource created.

Even if you don't buy that argument....

in the same format it is POSTED?

The Ur-example of a REST application is the world wide web. We download a form, fill it in, and submit. In most cases, the contents of the form travel to the server as an application/x-www-form-urlencoded collection of key value pairs. How often do you get one of those back from the server? Never, or some close approximation to, because the responses come back in text/html (or some similar variant).

If your "pragmatic approach" can point to a precedent on the world-wide-web, you are likely to be on solid ground.

Your Answer

By clicking "Post Your Answer", you acknowledge that you have read our updated terms of service, privacy policy and cookie policy, and that your continued use of the website is subject to these policies.

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