Я создаю свой первый RESTful API, и я заинтересован в лучших практиках при создании api, допустим, что я POST
до моей конечной точки /Document/
, чтобы создать новый Document
.Должен ли API возвращать данные, которые были созданы или обновлены?
Каков будет предпочтительный ответ с сервера?
Что-то, что предоставляет только сообщение с запросом, было успешным, или сообщение, которое указывает, что запрос был успешным, и вот информация, которая была создана?
Например:
{ message: 'Successfully created document' }
Или что-то вдоль линий:
{
message: 'Successfully created document',
data: {
id: 123456,
title: 'hello world',
body: 'this is the body'
}
}
Мы могли бы использовать коды состояния вместо message
, чтобы указать, был ли он успешным (т.е. 204
в первом ответе, 200
во втором?).
Есть ли предпочтительный способ выполнения этих ответов? Последний, по-видимому, скорее «соглашение о рукопожатии», а первый - это «большие пальцы».
Какие изменения возникают при обновлении Document
, есть ли больше аргументов для отправки обновленного object
или если формат остается неизменным?
Я думаю, что это полностью зависит от вас. «API» не плавает в воздухе, он служит цели какого-то «клиента». Итак, реальное дизайнерское решение действительно «что делает мой клиент после создания нового документа?». Если вам нужны какие-то действия, характерные для этого документа, которые требуют дополнительных данных, таких как идентификатор документа, а затем возвращают эти дополнительные данные. – Vinzzz