Is it ok by REST to return content after POST?

Question

I am using RESTlet and I have created a resource. I handle POST by overriding acceptRepresentation method.

The client should send me some data, then I store it to DB, set response to 201 (SUCCESS_CREATED) and I need to return some data to the client, but return type of acceptRepresentation is void.

In my case, I need to return some identificator so that client can access that resource.

For example, if I had a resource with URL /resource and the client sends POST request I add a new row in DB and its address should be /resource/{id}. I need to send {id}.

Am I doing something wrong? Does REST principles allow to return something after POST? If yes, how can I do it, and if no what is the way to handle this situation?

Answer 1

REST just says that you should conform to the uniform interface. In other words, it says you should do what POST is supposed to do as per the HTTP spec. Here is the quote from that spec that is relevant,

If a resource has been created on the origin server, the response SHOULD be 201 (Created) and contain an entity which describes the status of the request and refers to the new resource, and a Location header (see section 14.30).

As you can see from this, you have two places where you can indicate to the client where the newly created resource resides. The Location header should have an URL that points to the new resource and you can return an entity with the details also.

I'm not sure what the difference between overriding acceptRepresentation() and overriding post() but this example shows how to return a response from a POST.

Answer 2

I'd forgo sending anything in the body of the response. Just set Location: to the (full) URL of the newly created resource.

Your description suggests that this is exactly the semantics you:

1. POST a thing to create it
2. Respond with enough to know two things:
   1. That the creation happened (the 201)
   2. Where to find the new thing (the Location header)

Anything else is superfluous.

Answer 3

Two different questions:

Does the REST application pattern support returning data in a POST?

I don't think REST explicitly disallows it, but the preferred treatment is spelled out in Darrel's answer.

Does the RESTlet framework allow returning data in a POST?

Yes, even though it returns void, in a class which extends Resource, you have full access to the Response object object via the getResponse() method. So you can call getResponse().setEntity() with whatever data you want.

Answer 4

Output it in whatever format is requested. That might be:

<success>
    <id>5483</id>
</success>

Or:

{ "type": "success", "id": 5483 }

It depends on what you usually do. If they're not expecting the data, they should just ignore it, but any client that wants to handle it properly should be able to.

Answer 5

If you respond 201 Created with an entity body, rather than a Location redirect, then it's a good idea to include a Content-Location header pointing to the resource that is being represented in the response.

This will avoid potential confusion - in which a client could (justifiably) assume that the response entity actually represents a new state of the 'creator', and not the created resource.

> POST /collection
> ..new item..

< 201 Created
< Location: /collection/1354
< Content-Location: /collection/1354
< <div class="item">This is the new item that was created</div>