HTTP POST response Header header when creating multiple resources

Question

the HTTP / 1.1 standard states that if a POST operation results in a resource being created, then the response should include Location with the address of the new resource.

If the resource was created on the source server, the response SHOULD be 201 (Created) and contain an object that describes the status of the request and refers to the new resource, as well as the location (see section 14.30).

and in section 14.30

For answers 201 (Created), location is the location of a new resource that was created upon request.

Now suppose my API allows batch creation of resources using a POST array on the collection resource URL. For instance:

 POST /books [ { "name": "The Colour of Magic", "published": "1983" }, { "name": "The Light Fantastic", "published": "1986" } ] 

Since the two \book\{bookId} were created, what should be the value of the Location header in this case?

Http post response question after creating some new resources? similar, but it asks for the response object, not the headers (and does not respond).

Answer 1

I know this answer was late for the party, but I believe that the best solution is to create a new Batches resource with the uuid identifier, which will return a list of URLs of books that were added using a URL like this:

 http://api.example.com/batches/{uuid} 

eg.

 http://api.example.com/batches/2b9b251f71a4b2901d66e04725bc0c9cb5843c74 

Your POST or PUT can then return the above URL to the Location: {url} header and status code 201 - Created .

If you then GET this URL, it will be a list of URLs created in this batch, as well as any other information about the package, such as its uuid, and the time / date it was created.

 { "uuid": "2b9b251f71a4b2901d66e04725bc0c9cb5843c74", "datetime": "2005-08-15T15:52:01+00:00", "books": [ "http://api.example.com/books/the-colour-of-magic", "http://api.example.com/books/the-light-fantastic" ] } 

These resources can have a TTL of an hour or a month, no matter what you choose. They could live forever if you want; no matter what your use case requires.

Answer 2

RFC 2616 is deprecated. Stop looking at it except for historical purposes.

The current specification, RFC 7231, says:

"If one or more resources were created on the origin server as a result of successful processing of the POST request, the source server MUST send a 201 response (created) containing a location header field that provides the primary resource identifier (section 7.1.2) and a view describing the status of the request when accessing a new resource. " - http://greenbytes.de/tech/webdav/rfc7231.html#POST

And yes, this does not help when there is no “primary" resource.

Answer 3

I think you are using a specific use case for the Location header. In the case of mass creation, the processing result is usually provided within the returned content itself. In fact, processing can be fully or partially successful. I mean, all elements have been added, or just a subset, and the result shows the end user what is actually happening.

Therefore, I think the Location header cannot be used in this context. I see two options for the status code:

• Status code 201 , if at least one item is created)
• Status code 200 to indicate that the bulk request request is executed globally, but the result of each operation is described in the response content.

However, you may notice that there is a 202 status code if your resource handles bulk creations in an asynchronous way. But in this context, you need to pull the resource to get the status of the inserts.

Regarding the content of the answer, you are free to choose. We could imagine something like this:

 { "took": 4, "errors": true | false, "items": [ { "added": true, "error": null "id": "123" }, { "added": false, "error": { "code": "err12", "description": "validation error (field type, ...)" } "id": null } ] } 

ElasticSearch provides such an api array for creation, but also supports updating and deletion. See this link for more details: http://www.elastic.co/guide/en/elasticsearch/guide/current/bulk.html p>

Here are some similar questions that may give some clues:

• How to update the REST resource collection
• REST API - Bulk create or update in a single request

Hope this helps you, Thierry