В настоящее время я пишу API для социальной сети с Slim Framework. Мой вопрос: каковы лучшие практики, когда в структуре json нет строк для возврата?
Допустим, этот вызов / v1 / get / movies возвращает 2 строки из таблицы названий фильмов:
[
{"name": "Ghostbusters"},
{"name": "Indiana Jones"}
]
Но затем я вызываю / v1 / get / books и в этой таблице нет строк. Должен ли я просто вернуть пустую структуру?
[
]
... или было бы лучше сообщение и код ошибки?
[
"errors": {
"message": "no matches found",
"code": 134
}
]
Какая практика лучше? (API будет использоваться в приложениях iOS и Android) Спасибо!
programming-practices
rest
api-design
json
Андрес СК
источник
источник
[{"name": "..."}, {"name":"..."}]
Ответы:
Обычно я бы возвращал количество записей в результате в виде метаданных. Я не уверен, что это нормальная практика REST, но это не слишком много дополнительных данных, и это очень точно. Обычно для многих сервисов существует нумерация страниц, нецелесообразно сразу возвращать огромный набор результатов. Лично я раздражен, когда есть нумерация страниц для маленьких наборов результатов. Если это пусто, возврат
number_of_records : 0
и книги как пустой список / массивbooks : []
.РЕДАКТИРОВАТЬ (несколько лет спустя): Ответ от Мартина Викмана намного лучше, вот «краткое» объяснение, почему.
При работе с нумерацией страниц всегда помните о возможности изменения содержимого или порядка. Например, поступает первый запрос, 24 результата, вы возвращаете первые 10. После этого вставляется «новая книга», и теперь у вас есть 25 результатов, но с исходным запросом он будет упорядочен на 10-м месте. Когда первый пользователь запрашивает 2-ю страницу, он не получит «новую книгу». Существуют способы решения таких проблем, например, предоставление «идентификатора запроса», который должен быть отправлен с помощью следующих вызовов API, затем возврат следующей страницы из «старого» набора результатов, который должен быть каким-то образом сохранен и привязан к «идентификатору запроса». Альтернативой является добавление поля типа «список результатов изменен с первого запроса».
Как правило, если вы можете, постарайтесь приложить дополнительные усилия и избежать нумерации страниц. Разбиение на страницы - это дополнительное состояние, которое может быть видоизменено, а отслеживание таких изменений подвержено ошибкам, тем более, что и сервер, и клиент должны его обрабатывать.
Если у вас слишком много данных для одновременной обработки , рассмотрите возможность возврата «списка идентификаторов» со всеми результатами и подробностями для некоторого фрагмента этого списка и предоставьте вызовы API multi_get / get_by_id_list для ресурса.
источник
books
параметр является объектом, но «books» подразумевает более одного, а более одного подразумевает массив. Метаданные - это круто, и почти, в конечном счете, я ожидаю, что коллекция книг будет представлять собой массив объектов книги; если нет книг, просто дайте мне пустой массивВаш пример сломан. У вас не должно быть объектов json с дублирующимися ключами. То, что вы ищете, это массив с объектами фильма, например:
Этот подход также отвечает на ваш вопрос. Вы должны вернуть пустой массив, когда запрос не совпадает:
С другой стороны, если вы пытаетесь получить конкретный ресурс фильма,
GET api/movie/34
а этот фильм не существует, верните 404 с подходящим (закодированным в json) сообщением об ошибке в телеисточник
json_xs
.Если это JSON, вам следует рассмотреть возможность возврата массива объектов. Это имеет много преимуществ, включая то, что когда у вас нет записей, это пустой массив.
Поэтому, когда у вас есть записи, вы бы вернулись:
И когда у вас нет записей, вы бы вернулись:
источник
Если вы успешно выполнили операцию, но ей ничего не нужно возвращать, например, пустую карту
{}
или пустой массив,[]
я бы предпочел ответить кодом ответа 204, вот выдержка из спецификации определений кода состояния HTTP :По сути, я рекомендую использовать 204 в приложениях RESTful через HTTP, когда нечего возвращать.
источник
Была проделана разумная работа по созданию стандартизированного формата JSON API .
Следование принципам этой спецификации означает, что все возвращаемые ресурсы должны фактически быть «коллекциями» (даже если включен только один ресурс). Следование этому будет означать, что ваш вызов
/v1/get/movies
вернется:Ваш вызов
/v1/get/books
(который возвращает ноль ресурсов) вернет:источник
Для вашего конкретного примера я бы порекомендовал, чтобы / v1 / get / books возвращал HTTP 200 с пустым массивом.
Если я правильно читаю ваш пост, ваш API собирается собирать книги. Говоря метафорически, у вас есть книжная полка для книг, стойка для DVD для фильмов и, возможно, другие контейнеры, о которых вы здесь не упоминали. Поскольку вы намерены собирать книги, / v1 / get / books - это ваша книжная полка. Это означает, что там есть действительный ресурс - список книг, который в вашем конкретном примере оказался пустым.
Причина, по которой я не предлагаю возвращать HTTP 404 в этом случае, заключается в том, что книжная полка все еще там. На данный момент на нем нет книг, но это все еще книжная полка. Если бы это не была книжная полка - если API, например, не собирался собирать книги - тогда HTTP 404 подойдет. Но поскольку там есть ресурс, вы не должны сигнализировать, что его нет, что делает HTTP 404. Поэтому я утверждаю, что 200 с пустым массивом (означающим коллекцию) является более подходящим.
Причина, по которой я не предлагаю возвращать HTTP 204, заключается в том, что это означает, что «Нет содержимого» является обычным делом: выполнение этого действия на этом ресурсе обычно ничего не возвращает. Вот почему он обычно используется в качестве ответа на запросы DELETE, например: характер удаления обычно означает, что возвращать нечего. Аналогичный случай, когда он используется для ответа на запросы с семейством заголовков If-Modified: вы хотели контент только в том случае, если ресурс изменился, но это не так, поэтому я не дам вам никакого контента.
Но я утверждаю, что для получения пустой, но действительной коллекции HTTP 204 не имеет смысла. Если бы в коллекции были элементы, то правильным представлением был бы массив этих данных. Поэтому, когда там нет данных (но коллекция действительна), правильным представлением является пустой массив.
источник
Вы действительно должны сделать только одну из двух вещей
Либо верните
200 (OK)
код состояния и пустой массив в теле.Или верните
204 (NO CONTENT)
код состояния и НЕТ тела ответа.Мне вариант 2 кажется более технически правильным и соответствует принципам REST и HTTP.
Однако вариант 1 кажется более эффективным для клиента - потому что клиенту не нужна дополнительная логика для различения двух (успешных) кодов состояния. Поскольку он знает, что он всегда получит массив, ему просто нужно проверить, нет ли у него ни одного, одного или нескольких элементов, и обработать его соответствующим образом.
источник
Я видел оба случая в производственных условиях. Какой из них вы выберете, зависит от того, кто будет использовать API. Если они хотят знать, почему список пуст, или быть уверены, что список действительно пустой и при его получении не было ошибок, то вам следует прикрепить объект «ошибки». Если им все равно, возвращайте пустой список. Я бы выбрал второй подход, поскольку он охватывает больше потребностей, чем первый.
источник
Первое, что нужно учитывать, так как вы создаете RESTful API, - это вернуть соответствующий код ответа. И более подходящий код ответа, чтобы сообщить, что запрос прошел нормально, но запрошенный ресурс в данный момент недоступен, - это почтенный 404.
Если вы разрабатываете свой API таким образом, что он всегда возвращает разумный код ответа, вам может даже не понадобиться возвращать тело, когда ресурс не найден. Тем не менее, возвращение тела, особенно читаемого человеком, не повредит.
Здесь нет «лучшей практики», оба ваших примера произвольны, просто выберите один и будьте последовательны . Разработчики ненавидят сюрпризы, если они
/v1/get/movies
возвращаются,{}
когда нет фильмов, тогда мы ожидаем,/v1/get/actors
что они вернутся,{}
когда нет актеров.источник
Я не думаю, что правильный ответ - тот, который отмечен.
Ответ, предоставленный nirth, должен быть лучшим в истинном сценарии REST. Ответ тела должен быть пустым, а код статуса http: 204; ресурс существует, но в то время у него нет содержимого: он пуст.
REST HTTP_Status_Codes
источник
Я рекомендую 200+ пустой массив, так как он упрощает обработку всеми клиентами API. 200 + массив означает «я вернул все данные, которые есть». Как для кода, доставляющего данные, так и для кода, обрабатывающего их, количество элементов не имеет значения.
Любой другой код состояния должен быть надлежащим образом задокументирован и надлежащим образом доставлен сервером и надлежащим образом обработан клиентом, и мы все знаем, насколько вероятно, что это произойдет.
Было предложение вернуть статус 204 + пустое тело. Это означает , что вы вынуждаете каждый одного клиента в состояние 204 процесса правильно. Более того, вы заставляете их обрабатывать не-JSON ответы! Я надеюсь, что все понимают, что только потому, что запрос получил ответ, это не означает, что ответ пришел с сервера при использовании http, и просто проверка того, что ответом является JSON, обрабатывает многие из этих случаев.
источник
Я бы "Это зависит".
Если ноль - разумный результат, верните пустой список. Например, если вы хотите, чтобы все сотрудники назывались «боб», где «никто» - вполне разумный результат. Если это не ожидаемый результат, верните ошибку. Например, получение исторического списка уличных адресов для человека, которого вы нанимаете. Они должны где-то жить, чтобы результат не был ошибкой, а не просто нормальным состоянием.
Я уверен, что вы можете спорить со спецификой моего примера, но вы поняли ...
источник
get
в вашем URL нет RESTful, GET подразумевается методом HTTP.GET
api/movies
вернуть200 OK
с пустым массивом[]
.GET
api/movies/1
(где1
идентификатор), а он не существует, верните a404 Not Found
.Почему? Вы запрашиваете ресурсы . Когда вы запрашиваете коллекцию, сам ресурс (коллекция) существует. Поэтому
404
неправильно. Но если вы запрашиваете определенный фильм, а он не существует, запрошенный ресурс не существует, и вы должны вернуть a404
.источник
Если вы возвращаете JSON, лучше всегда возвращать счетчик и сообщение об ошибке и, возможно, логическое значение, указывающее, есть ли ошибка или нет, это мои стандартные три мета-значения, возвращаемые с каждым списком строк.
источник