What to include in a (Batch) POST/PATCH results/errors for results for pragmatic REST API

Question

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!

Answer 1

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.