Должен ли HTTP API всегда возвращать тело?

Есть ли какой-то стандарт в отношении ответов HTTP API?

Прочитав эту беседу я начал задумываться. Мы разрабатываем наш общедоступный HTTP JSON API на моей работе, и мы ничего не возвращаем, когда это не является строго необходимым (например, PUT для / resource / {id} возвращает только 200, когда OK или соответствующий код 4XX или 5XX, но нет JSON body)

Должны ли мы возвращать общий тип, {"success":true}как они обсуждают по этой ссылке выше, или это нормально, чтобы возвращать «пустое» тело и обрабатывать все с помощью http-кодов ответов?

Относительно PUT, но относится и к POST. Спецификации HTTP раздел 9 немного пусто по правилам или даже советы (должны) , когда речь идет о сценарии , который вы описываете. Строка, относящаяся к вашему вопросу, наиболее тесно связана с:

Если новый ресурс создан, сервер происхождения ДОЛЖЕН проинформировать пользовательский агент через ответ 201 (Создано). Если существующий ресурс изменен, то должны быть отправлены коды ответа 200 (ОК) или 204 (Нет содержимого), чтобы указать успешное завершение запроса.

Я не думаю, что потерял бы из-за этого сон, но я бы спросил, что вы получите, добавив кусок JSON в ответ? Вы только что выполнили (ОК, возможно, переполнены!) Ответ, повторяющий менее точно то, что код статуса уже должен был вам сказать. Если ваш PUT привел к новому объекту, верните 201 (как и задумано PUT), если он обновил объект, верните 204.

Кстати, кроме API, вместо 200, если вы ничего не возвращаете, используйте 204.

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

Базовый стандарт HTTP не требует, чтобы был документ, возвращенный с ответом. Ради экономии, когда HTTP-статус передает все, что требуется, тело будет расточительным. Тем не менее, существуют стандарты, основанные на HTTP, которые добавляют новые правила.

Существует открытый стандарт JSON API, который определяет:

• Объект JSON ДОЛЖЕН быть в корне каждого ответного документа JSON API . (курсивом обозначено то, что я добавил для уточнения текста)

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

Некоторые приложения (например, ElasticSearch ) предоставляют полный API- интерфейс JSON и всегда имеют некоторые метаданные, чтобы вы могли лучше понять, как сервер управляет вашими данными. Стандартный объект ответа сообщает вам о работоспособности индекса, если запрос привел к ошибке, сколько узлов было затронуто и т. Д. ElasticSearch использует «application / json» для mime-типа, поэтому маловероятно, что они применяют рекомендации в стандарт jsonapi.org.

JQuery и подобные платформы Javascript предполагают, что документ всегда будет. Вопрос в том, какую проверку ошибок вы хотите навязать своим пользователям API? Если вы предлагаете стандартный формат для всех ответов, который расширяется только на основе типа запроса, вы удовлетворяете потребность в возвращаемом документе и облегчаете отладку пользователями API.

Нет, например, для 204 ответов мы не должны включать тело сообщения. {success | status | isSuccessful: true} является избыточным.

На практике (или я должен сказать в более поздней версии jquery) пустой ответ для типа содержимого application / json вызывает ошибку. Я вроде понимаю аргумент, что, поскольку это application / json, у него должно быть допустимое тело json. Таким образом, пустой ответ для типа контента application / json будет 'null' или '{}', которые являются допустимыми json.

Есть другой способ, который должен работать для jquery, это не возвращать application / json для пустых ответов. Просто используйте text / plain или что-то еще и убедитесь, что клиент может обработать этот тип.

Обратите внимание, я могу вспомнить только 204 для явного запрета возврата тела сообщения. Мы обнаружили, что не всегда можем использовать 204. Проблема в том, что MSIE отбрасывает заголовок ответа для 204 ответов, поэтому нет содержимого и заголовков, что плохо. Поскольку многие используют MSIE, нам пришлось изменить его на 200 статус.

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

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

Для запросов PUT, PATCH и POST вы обычно возвращаете состояние, возвращающее состояние ресурса после применения запроса, а не пустой ответ.

Для запросов POST , которые представляют действия вместо того , чтобы просто создать ресурс (не очень успокоительный, но по- прежнему полезны на практике), которые не имеют полезные данные для возвращения, я бы вернуть ответ , состоящий из пустого объекта JSON, то есть {}. Таким образом, клиент получает действительный ответ, и добавление некоторой информации в дальнейшем вряд ли сломает его.

Для запросов DELETE возвращается 204, и пустое тело довольно распространено, что имеет смысл, поскольку ресурс впоследствии не существует.

Я бы предложил вернуть только то, что нужно + небольшое уточнение.

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

Таким образом, POST {key: 123} может вернуть {key: 123, foo: 'bar'}.

Основная идея заключается в том, что лучше вернуть объект, чем снова запрашивать его.

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

Обычно я возвращаю {success: true} или что-то подобное, когда нет необходимости в объектах POST PUT и PATCH, потому что это облегчает работу принимающей стороны. Тем не менее, лучше в 99% случаев возвращать сохраненное представление объекта, редко когда им это все равно не нужно, и «дешевле» отправить все это в одном запросе, а не в двух.

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

Возвращение 200 {success: true} позволяет людям писать код в обоих направлениях:

if response.code == 200
  do stuff
end

а также

if response.body.success
  do stuff
end

Кроме того, это не так сложно сделать на вашей стороне.

И наконец (извините за структуру ответов poos), предоставляя общедоступный API-интерфейс JSON, вы отказываетесь от большого контроля над тем, как он будет использоваться. Некоторые клиенты могут по-разному реагировать на разные органы (или их отсутствие) или коды состояния.