Каким должен быть ответ API для уже выполненных или ненужных операций

Какой ответ (код + контент) я должен вернуть, когда мой JsonAPI запрашивается для выполнения какой-либо операции, которая уже была выполнена или не имеет смысла?

Пример: предположим, я хочу запросить публикацию статьи. Черновик статьи обновляется через конкретную конечную точку (здесь не имеет значения), и есть конкретная конечная точка для публикации (чей ответ нас интересует)

4 разных сценария, мне нужно выяснить, какой тип ответа отправлять каждый раз:

  1. Публикация никогда не запрашивалась, и в статье есть вся обязательная информация о публикации, имеет смысл запросить публикацию, поэтому я возвращаю принятый ответ 202 с ресурсом статьи, включая атрибут «публикация запрошена в»

  2. Успешный запрос на публикацию публикации уже был отправлен/подтвержден, и ни у кого не было времени просмотреть его в промежутке между ними. Что мне вернуть?

  3. Предыдущий запрос на публикацию был кем-то рассмотрен и принят (статья теперь опубликована). API снова получает запрос на публикацию этой статьи, которая уже была опубликована, это не имеет смысла, что я должен вернуть?

  4. В статье не заполнена вся обязательная информация, и кто-то делает запрос на публикацию. Я должен сообщить пользователю, что его запрос не был удовлетворен из-за ошибок. Я думал, что для этого я мог бы вернуть список ошибок проверки. Звучит честно?


api rest json-api http-response-codes jsonapi-resources
person Cyril Duchon-Doris    schedule 11.06.2017    source источник

Ответы (1)


arrow_upward
1
arrow_downward

Ваши первые две пули...

  • Публикация никогда не запрашивалась, и в статье есть вся обязательная информация о публикации, имеет смысл запросить публикацию, поэтому я возвращаю принятый ответ 202 с ресурсом статьи, включая атрибут «публикация запрошена в»
  • Успешный запрос на публикацию публикации уже был отправлен/подтвержден, и ни у кого не было времени просмотреть его в промежутке между ними. Что мне вернуть?

...поддаются 202 Accepted:

202 Accepted: Запрос принят в обработку, но обработка не завершена. Запрос может быть или не быть в конечном счете обработан, и может быть запрещен, когда происходит обработка.

Ваша третья пуля:

  • Предыдущий запрос на публикацию был кем-то рассмотрен и принят (статья теперь опубликована). API снова получает запрос на публикацию этой статьи, которая уже была опубликована, это не имеет смысла, что я должен вернуть?

Я бы, вероятно, использовал здесь перенаправление 303:

303 См. другое. Ответ на запрос можно найти по другому URI с помощью метода GET. При получении в ответ на POST (или PUT/DELETE) клиент должен предположить, что сервер получил данные, и должен выполнить перенаправление с отдельным сообщением GET.

Но вы также можете рассмотреть возможность постоянной переадресации 308:

Постоянное перенаправление 308 (RFC 7538): запрос и все будущие запросы должны повторяться с использованием другого URI. 307 и 308 аналогичны поведению 302 и 301, но не позволяют изменять метод HTTP. Так, например, отправка формы на ресурс с постоянным перенаправлением может продолжаться гладко.

Но я бы склонялся к 303.

И твоя последняя пуля:

  • В статье не заполнена вся обязательная информация, и кто-то делает запрос на публикацию. Я должен сообщить пользователю, что его запрос не был удовлетворен из-за ошибок. Я думал, что для этого я мог бы вернуть список ошибок проверки. Звучит честно?

Это стандартный "плохой клиентский запрос" (4xx) с ошибками:

400 Bad Request: сервер не может или не будет обрабатывать запрос из-за очевидной ошибки клиента (например, неверный синтаксис запроса, слишком большой размер, неверный кадр сообщения запроса или ложная маршрутизация запроса).

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

Запомнить:

  • Ответы 2xx означают успех
  • Ответы 3xx указывают на перенаправление
  • Ответы 4xx указывают на сбой со стороны клиента
  • Ответы 5xx указывают на сбой со стороны приложения, обслуживающего запрос.

Источник: Список кодов состояния HTTP

person rianjs    schedule 11.06.2017