20

I have put together an API that responds to a POST request by putting the content of the new resource in the response body, and the URL of the new resource in the Location HTTP response header.

Sample request:

POST /api/v1/widgets HTTP/1.1
Content-type: application/json;
Accept: application/json;

{
    "name": "[email protected]",
    "price": "10",
}

Sample response:

HTTP 201 Created
Location: http://example.com/api/v1/widgets/123456

{
    'widget': 
    {
        'id': "123456",
        'created': "2012-06-22T12:43:37+0100",
        'name': "[email protected]",
        'price': "10",
    },
}

Someone has raised an issue that the URL should also be in the body of the response. Is there a best practice on this?

1
  • (Feel free to kill this if it is too subjective - not sure whether this contravenes the spirit of SO or not) Jun 22, 2012 at 15:36

4 Answers 4

15

There is a reason for not putting the location (URL) of the newly created resource) in the body: the URL is metadata needed for the message interaction among service consumers and services, it's not "business data". There is a SOA Design Pattern called "Messaging Metadata" that suggests that URLs, security credentials, correlation identifiers, transaction IDs and other messaging and composition context data should be placed in headers, not in the body of the messages. Indeed, http already provides the standard header Location for that.

OTOH, if your REST service uses HATEOAS the response may contain one or more URLs that are direct links to operations you want to offer for consumers to dynamically bind and call.

I think having the URL in both header and body is the worst solution. Redundant data is prone to inconsistency in the long run.

11

I would put it in the header (as Location: http://blah.blah.com/blah). You could put it in your body as well if you want (in whatever appropriate format you are sending), and it wouldn't be improper.

The atompub REST API is usually a good reference for a good REST API. They put it in both.

HTTP/1.1 201 Created
Date: Fri, 7 Oct 2005 17:17:11 GMT
Content-Length: nnn
Content-Type: application/atom+xml;type=entry;charset="utf-8"
Location: http://example.org/edit/first-post.atom
ETag: "c180de84f991g8"  

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Atom-Powered Robots Run Amok</title>
  <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
  <updated>2003-12-13T18:30:02Z</updated>
  <author><name>John Doe</name></author>
  <content>Some text.</content>
  <link rel="edit"
      href="http://example.org/edit/first-post.atom"/>
</entry>
2
  • Thanks for the reply - having a benchmark like atompub is just what I was looking for. Jun 23, 2012 at 13:19
  • 4
    Yes, but note that the URI in the example returned body from AtomPub shown above is actually a link which tells the receiver what URI to use if they want to "edit" the resource (following the HATEOAS principle). It isn't, strictly speaking, necessarily the same as URI of the resource itself (i.e. not necessarily the same as the value in the Location: header, which tells where you could GET the resource). It happens that in this example, the URI to GET the resource and the one used to edit the resource is the same. Jun 23, 2012 at 15:57
2

Just to add to this old topic

This seems to be a RFC defined standard so some clients may rely on this - didn't test how browsers will behave, but I would say that 201 + Location header will cause the redirect (to the Location resource) as in case of 301, 303 and 307.

see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/201

or RFC:

https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.2

On other hand, most of API clients will use some kind of 'fetch' functionality without following redirects. The data will be expected to be in the body (not URLs of resources, but some kinds of IDs)

0

Though the original post in very old the question is still relevant and the correct anwer probably has changed.

The old king - REST-APIs as defined by Fielding in 2000 - is dead for machine-to-machine communication.

The new king is "Open-API"-specified-API.

Its not the same. The most important difference is that REST by Fielding imagined a web that can be explored my means of HATEOAS. It was basically an adventure "full of unexpected options and suprises"

Open-API is in some sense the opposite. It is a strict contract that defines what operations can be called with what parameters and what results can be expected. There no element of suprise involved. Though this may sound boring, it is a very good characteristic for machine-to-machine communication.

The typical consumer of an "Open-API"-API generates client code out of the specification file. The generated code will automatically provide methods for the API-operations. Each method will expect parameters and a defined return type. Parameters will typically not be URLs. For that reason a URL in the location header will typically not be useful. Often it would need to be parsed "manually" in order to extract things such as business keys. That is annoying for the consumer.

Redirects are usually even worse. A method usually defines a definte return type. The consumer calls the operation and expects a definte return type. A redirect will typically redirect to some other operation defined by "Open-API". It may have a completely different return type. This is very annoying for the consumer. To my knowledge there is no means to actually reference the Open-API-operation to which is redirected by a Location header.

For those reasons i think the correct answer by now is:

For "Open-API"-APIs (formely known as REST) put URLs NEITHER into the Location header NOR into to Body.

Put data into the body that will serve as paramers to the subsequent API-calls. And don't use redirects to other Open-API-operations.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

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