Что должен возвращать RESTful API POST / DELETE в теле?

Question

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

• POST / person / bob / follow
• DELETE / person / bob / follow

Что они должны вернуть в теле?

1. Собрание всех, за кем вы следуете
2. Человек, за которым вы следили / не подписался
3. Статус, подобный {статус: "ок"}
4. Ничего.

Answer 1

Если вы отвечаете на ошибки, используя статус HTTP-сервера, код состояния ничего не говорит.Если вы ответите 404 Not Found, если нет пользователя Bob, или 500 Internal Server Error, если база данных повреждена, единственный успешный ответ, который вы когда-либо получите, - ОК.Пользователям не нужно проверять код состояния, они должны только проверять код состояния HTTP.

Я предлагаю вам ничего не возвращать, а также тот факт, что это успешный ответ (т.е. 200 OK или 204 Нет содержимого)указывает на то, что операция прошла успешно.

Answer 2

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

Как: respond(ResponseCode::OK, ...)Для POST: я бы возвратил объект 'bob', содержащий всех его последователей + код статусаДля DELETE: я бы только вернул код состояния.

Answer 3

Как правило, для API я извиняюсь за использование кодов состояния HTTP вместо всегда ОК с определенным кодом статуса.Это означает, что вы можете следовать существующим стандартам для ответов, и любой, кто получит код ошибки, будет примерно знать, что произошло / что он должен сделать.Взгляните на вики-статью http коды состояния , где приведено полезное справочное руководство.

Кроме того, вместе с кодом ошибки, и поскольку речь идет об API, полезноиметь более описательное сообщение об ошибке.Что-то значимое, например ошибка: «Отсутствует токен аутентификации» или любой другой стандарт, который вы можете придумать.

Когда речь идет о создании ресурсов, я обычно отвечаю с помощью 201 (Создано) и только что созданного ресурса.Помните, что вы можете исключить некоторые атрибуты из ресурса (например, вы создаете пользователя, вы не должны возвращать конфиденциальную информацию, такую ​​как зашифрованный пароль)

Что касается удаления ресурсов, обычно возвращаютсяс 200 (Ok) или 202 (Accepted) и без дополнительной информации.

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