«Лучшая» практика для спокойного POST-ответа

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

Я создаю новый ресурс повторно, говорю:

/books (POST)

с телом:

{
  title: 'The Lion, the Witch and the Wardrobe',
  author: 'C. S. Lewis'
}

Я знаю, что должен вернуть 201 (Created) с заголовком Location нового ресурса:

Location: /books/12345

Вопрос, на который я не могу ответить сам, заключается в том, что сервер должен вернуть в теле.

Я часто делал такой тип ответа:

{
  id: 12345,
  title: 'The Lion, the Witch and the Wardrobe',
  author: 'C. S. Lewis'
}

Я сделал это по нескольким причинам:

1. Я написал API для рамок переднего конца, как angularjs. В моем конкретном случае я использую угловые ресурсы, и мне часто нужен только идентификатор ресурса, чтобы найти его. Если я не вернул идентификатор в теле ответа, мне нужно было бы проанализировать его из заголовка Location.
2. В GET всех книг я обычно возвращаю весь объект, а не только идентификатор. В этом смысле мой клиентский код не должен различать, откуда взять идентификатор (заголовок местоположения или тело).

Теперь я знаю, что я действительно нахожусь в серой зоне, но большинство людей говорят, что возвращать весь ресурс - это «плохая» практика. Но что, если сервер изменяет / добавляет информацию к ресурсу. Это определенно добавляет идентификатор, но может также добавить другие вещи, такие как отметка времени. В случае, если я не возвращаю весь ресурс, действительно ли лучше сделать POST, вернуть идентификатор, а затем заставить клиента выполнить GET для получения нового ресурса.

Возврат всего объекта при обновлении не очень уместен, но я не могу понять, почему возврат всего объекта при его создании был бы плохой практикой в ​​обычном случае использования. Это было бы полезно по крайней мере, чтобы легко получить идентификатор и получить метки времени, когда это уместно. Это на самом деле поведение по умолчанию, полученное при скаффолдинге с Rails.

Я действительно не вижу никакого преимущества в возврате только идентификатора и выполнении запроса GET после, чтобы получить данные, которые вы могли бы получить с вашим первоначальным POST.

В любом случае, пока ваш API согласован, я думаю, что вы должны выбрать шаблон, который наилучшим образом соответствует вашим потребностям. Не существует правильного способа построения REST API, imo.

Возврат нового объекта соответствует принципу REST «Унифицированный интерфейс - управление ресурсами посредством представлений». Полный объект - это представление нового состояния объекта, который был создан.

Вот действительно отличная справочная информация по разработке API, здесь: Лучшие практики для разработки Pragmatic RESTful API

Он включает в себя ответ на ваш вопрос здесь: Обновления и создание должны возвращать представление ресурса

Это говорит:

Чтобы предотвратить повторное использование потребителем API обновленного представления для API, попросите API вернуть обновленное (или созданное) представление как часть ответа.

Мне это кажется прагматичным, и это соответствует принципу REST, о котором я упоминал выше.