Ответ REST - должен ли я помещать URL-адрес нового ресурса в заголовок, тело или и то, и другое?

Я собрал API, который отвечает на запрос POST, помещая содержимое нового ресурса в тело ответа и URL-адрес нового ресурса в заголовок ответа HTTP-адреса местоположения.

Пример запроса:

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

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

Пример ответа:

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",
    },
}

Кто-то поднял вопрос о том, что URL-адрес должен также находиться в теле ответа. Есть ли лучшая практика в этом?

Ответы

Ответ 1

Я бы поместил его в заголовок (как Location: http://blah.blah.com/blah). Вы можете поместить его в свое тело, если хотите (в любом подходящем формате, который вы отправляете), и это было бы неправильно.

atompub REST API обычно является хорошей ссылкой для хорошего API REST. Они положили его в оба.

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

Существует причина не помещать местоположение (URL) вновь созданного ресурса) в тело: URL-адрес метаданных, необходимых для взаимодействия сообщений между потребителями услуг и услугами, а не "бизнес-данные". Существует шаблон проектирования SOA под названием "Метаданные сообщений" , в котором указаны URL-адреса, учетные данные безопасности, идентификаторы корреляции, идентификаторы транзакций и другие данные контекста обмена сообщениями и компоновки должны размещаться в заголовках, а не в теле сообщений. Действительно, http уже предоставляет стандартное заголовок для этого.

OTOH, если ваша служба REST использует HATEOAS, ответ может содержать один или несколько URL-адресов, которые являются прямыми ссылками на операции, которые вы хотите предложить потребителям для динамического связывания и вызова.

Я думаю, что URL-адрес в заголовке и теле является наихудшим решением. Избыточные данные подвержены несогласованности в долгосрочной перспективе.