Как вернуть сгенерированный идентификатор в RESTful POST?

Скажем, у нас есть услуга, чтобы добавить новый отель:

> POST /hotel
> <hotel>
>   <a>aaa</a>
>   <b>aaa</b>
>   <c>aaa.......this is 300K</c>
> </hotel>

И тогда у нас есть get:

> GET /hotel

< HTTP/1.1 200 OK
< <hotel>
<   <a>aaa</a>
<   <b>aaa</b>
>   <c>aaa.......this is 300K</c>
< </hotel>

Вопрос: что мы возвращаем для первоначального создания POST? Мы хотели бы вернуть идентификатор (сгенерированный на сервере) для "ссылки" на новый ресурс, но мы не хотим возвращать все данные отеля, так как в нашем случае одно из полей данных представляет собой плоский файл размером ~ 300 тыс..

Итак, вы должны просто вернуться:

< HTTP/1.1 200 OK
< <hotel>
<   <id>123</id>
< </hotel>

Или вы должны вернуть полный объект:

< HTTP/1.1 200 OK
< <hotel>
<   <id>123</id>
<   <a>aaa</a>
<   <b>aaa</b>
>   <c>aaa.......this is 300K</c>
< </hotel>

??

Меня интересует спокойная передовая практика.

Примечание: этот связанный пост говорит больше о том, что возвращать, но меньше о том, как вернуть его.

Ответы

Ответ 1

Верните код состояния 201 - Создано и поместите URL-адрес в заголовок Location. Вам вообще не нужно возвращать тело.

Ответ 2

REST - это все о URL-адресах ресурсов.

Лучшая практика RESTful - вернуть URL-адрес, используемый для доступа к только что созданному ресурсу.

Я бы не вернул весь документ. Если это не важно для протокола по какой-либо причине (например, сервер может изменить данные, которые клиент отправляет, и клиент хочет подтвердить, что это нормально). Если это не важно, клиент уже знает данные.

Если вы вернете только идентификатор, клиент не будет знать, что с ним делать. Но возврат URL-адреса позволит клиенту продолжить взаимодействие REST с сервером (предположительно, получив документ описания услуги). Это не означает, что вы не можете вернуть идентификатор вместе с URL-адресом. Но URL-адрес, потому что это веб-система, является самой важной информацией, которую вы можете знать. Кроме того, идентификатор, вероятно, будет чем-то, что вам нужно внутренне для вашего бэкэнд, а не то, о чем клиент должен когда-либо беспокоиться.

EDIT:
Что касается того, следует ли переносить возвращаемый URL в XML, это действительно зависит от вашего протокола. Если вы считаете, что можете захотеть вернуть другие данные в будущем, XML будет более осмотрительным. Наличие именованного формата файла позволит вам улучшить ваши службы (изменив заголовок типа документа). Но вы можете просто вернуть URL-адрес.

Ответ 3

Единственным преимуществом возврата заголовка местоположения и фактического тела объекта в ответ является то, что клиент может получить результирующее представление в одном обратном направлении на сервер. AtomPub делает это, например.