7

I have a simple server API:

The client can upload a file. The server returns 201 Created if it was successful. The http response has a Location header which points to the new created resource.

Now we face a new use case: One http request should be able to create N new resources.

I am unsure how to implement this according to the http spec.

AFAIK there most be only exactly one Location header.

How to return N URLs in a http 201 Created response?

My question is related, but not a duplicate of the following question, since the question there is clearly answered with "No". My question is different: How to ...

My question is not "Is it allowed to return several Location header?".

Can the Location header be used for multiple resource locations in a 201 Created response?

guettli
  • 25,042
  • 81
  • 346
  • 663
  • Possible duplicate of [Can the Location header be used for multiple resource locations in a 201 Created response?](https://stackoverflow.com/questions/11309444/can-the-location-header-be-used-for-multiple-resource-locations-in-a-201-created) – jonrsharpe Dec 18 '17 at 08:52
  • @jonrsharpe I explained why my question is not a duplicate. Yes, both questions are related, but they are different. – guettli Dec 18 '17 at 10:11
  • The first answer says no, the second answers gives an alternative. – jonrsharpe Dec 18 '17 at 10:12
  • @jonrsharpe yes the second answer of the possible duplicate explains more. But it does not really answer my question, since several Location headers are not allowed. – guettli Dec 18 '17 at 10:16
  • 1
    there is 207 (Multi-Status) response type proposed in [rfc4918](https://tools.ietf.org/html/rfc4918). – georgexsh Dec 21 '17 at 07:17
  • @georgexsh I think rfv4918 (https://tools.ietf.org/html/rfc4918#section-13) is a valid answer. If you write at as answer, then I will upvote it. – guettli Dec 21 '17 at 11:49

2 Answers2

9

You could take a look at rfc4918, which proposed a new type of response, 207 (Multi-Status), short description copied from REST & WOA Wiki:

A Multi-Status response conveys information about multiple resources in situations where multiple status codes might be appropriate. The default Multi-Status response body is a text/xml or application/xml HTTP entity with a 'multistatus' root element. Further elements contain 200, 300, 400, and 500 series status codes generated during the method invocation. 100 series status codes SHOULD NOT be recorded in a 'response' XML element.

Community
  • 1
  • 1
georgexsh
  • 15,984
  • 2
  • 37
  • 62
6

How to return N URLs in a http 201 Created response?

Short answer: in the message-body.

Longer answer:

I think you are going about your search somewhat backwards.

In HTTP; the status code and the response headers are metadata; the accompany the message to give the generic http components a context agnostic way of understanding what happened.

Broadly, the metadata is derived from the data. So start with the payload.

In the case of a 201 CREATED response:

The 201 response payload typically describes and links to the resource(s) created.

Your first step is to create this representation; in the case where you are working in HTML, it would look like a web page with "congratulations, everything worked" and a bunch of marked up text with hyperlinks to provide the client with access to the new resources.

Having done that, you now review that representation to see what information should be lifted into the standard headers so that generic components can also understand some of what is going on.

For example, see the description of POST responses

If one or more resources has been created on the origin server as a result of successfully processing a POST request, the origin server SHOULD send a 201 (Created) response containing a Location header field that provides an identifier for the primary resource created (Section 7.1.2) and a representation that describes the status of the request while referring to the new resource(s).

So we identify which of the resources created is the primary, and lift the identifier of that resource from the representation into the Location header.

Identifiers for the secondary resources are still available in the message body. If you need to expose those resources to the generic components as well, then you might use a Link header.

Community
  • 1
  • 1
VoiceOfUnreason
  • 52,766
  • 5
  • 49
  • 91
  • Thank you for this detailed answer! Just one problem: There is no "primary" or "secondary" resource. There is a set of resources with no ordering. But the Link-Header looks good. – guettli Dec 19 '17 at 12:00