"Найкраща" практика для спокійного реагування на пошту

Тож нічого нового тут я просто намагаюся отримати дещо роз’яснення і не можу знайти жодного в інших публікаціях.

Я створюю новий ресурс спокійно, скажіть:

/books (POST)

з тілом:

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

Я знаю, що я повинен повернути 201 (Створений) із заголовком 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, щоб отримати новий ресурс.

Повернення цілого об'єкта в оновлення не здасться дуже доречним, але я навряд чи бачу, чому повернення всього об’єкта при його створенні було б поганою практикою у звичайному випадку використання. Це було б корисно принаймні для того, щоб легко отримати ідентифікатор та отримати часові позначки, коли це доречно. Це насправді поведінка за замовчуванням, отримана під час риштування з рейками.

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

У будь-якому випадку, поки ваш API є послідовним, я думаю, що вам слід вибрати образець, який найкраще відповідає вашим потребам. Не існує жодного правильного способу створення API REST, imo.

Повернення нового об'єкта відповідає принципу REST "Уніфікований інтерфейс - маніпуляція ресурсами через представлення". Повний об'єкт - це подання нового стану об’єкта, який був створений.

Тут справді відмінна посилання на дизайн API, тут: Кращі практики для проектування прагматичного API RESTful

Він включає відповідь на ваше запитання тут: Оновлення та створення повинні повертати представлення ресурсів

Він говорить:

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

Здається мені досить прагматично, і це відповідає тому принципу REST, про який я згадував вище.