REST response - should I put the URL of the new resource in the header, body, or both?

Question

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?

Answer 1

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.

Answer 2

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>