RESTful API дизайн. Что я должен вернуть, если нет строк?

В настоящее время я пишу 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) Спасибо!

Обычно я бы возвращал количество записей в результате в виде метаданных. Я не уверен, что это нормальная практика REST, но это не слишком много дополнительных данных, и это очень точно. Обычно для многих сервисов существует нумерация страниц, нецелесообразно сразу возвращать огромный набор результатов. Лично я раздражен, когда есть нумерация страниц для маленьких наборов результатов. Если это пусто, возврат number_of_records : 0и книги как пустой список / массив books : [].

{
    meta: {
        number_of_records : 2,
        records_per_page : 10,
        page : 0
    },
    books : [
        {id:1},
        {id:27}
    ]
}

РЕДАКТИРОВАТЬ (несколько лет спустя): Ответ от Мартина Викмана намного лучше, вот «краткое» объяснение, почему.

При работе с нумерацией страниц всегда помните о возможности изменения содержимого или порядка. Например, поступает первый запрос, 24 результата, вы возвращаете первые 10. После этого вставляется «новая книга», и теперь у вас есть 25 результатов, но с исходным запросом он будет упорядочен на 10-м месте. Когда первый пользователь запрашивает 2-ю страницу, он не получит «новую книгу». Существуют способы решения таких проблем, например, предоставление «идентификатора запроса», который должен быть отправлен с помощью следующих вызовов API, затем возврат следующей страницы из «старого» набора результатов, который должен быть каким-то образом сохранен и привязан к «идентификатору запроса». Альтернативой является добавление поля типа «список результатов изменен с первого запроса».

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

Если у вас слишком много данных для одновременной обработки , рассмотрите возможность возврата «списка идентификаторов» со всеми результатами и подробностями для некоторого фрагмента этого списка и предоставьте вызовы API multi_get / get_by_id_list для ресурса.

Ваш пример сломан. У вас не должно быть объектов json с дублирующимися ключами. То, что вы ищете, это массив с объектами фильма, например:

 [
    {"name": "movie1"}, 
    {"name": "movie2"}
 ]

Этот подход также отвечает на ваш вопрос. Вы должны вернуть пустой массив, когда запрос не совпадает:

[]

С другой стороны, если вы пытаетесь получить конкретный ресурс фильма, GET api/movie/34а этот фильм не существует, верните 404 с подходящим (закодированным в json) сообщением об ошибке в теле

Если это JSON, вам следует рассмотреть возможность возврата массива объектов. Это имеет много преимуществ, включая то, что когда у вас нет записей, это пустой массив.

Поэтому, когда у вас есть записи, вы бы вернулись:

    [
        {"name": "Ghostbusters"},
        {"name": "Indiana Jones"}
    ]

И когда у вас нет записей, вы бы вернулись:

    [

    ]

Если вы успешно выполнили операцию, но ей ничего не нужно возвращать, например, пустую карту {}или пустой массив, []я бы предпочел ответить кодом ответа 204, вот выдержка из спецификации определений кода состояния HTTP :

Сервер выполнил запрос, но ему не нужно возвращать тело объекта, и он может захотеть вернуть обновленную метаинформацию. Ответ МОЖЕТ включать новую или обновленную метаинформацию в форме заголовков объекта, которые, если они присутствуют, ДОЛЖНЫ быть связаны с запрошенным вариантом.

Если клиент является агентом пользователя, он НЕ ДОЛЖЕН изменять представление своего документа по сравнению с тем, что вызвало отправку запроса. Этот ответ в первую очередь предназначен для того, чтобы ввод данных для действий происходил, не вызывая изменений в активном представлении документа агента пользователя, хотя любая новая или обновленная метаинформация ДОЛЖНА применяться к документу, который в данный момент находится в активном представлении агента пользователя.

Ответ 204 НЕ ДОЛЖЕН включать тело сообщения и, таким образом, всегда заканчивается первой пустой строкой после полей заголовка.

По сути, я рекомендую использовать 204 в приложениях RESTful через HTTP, когда нечего возвращать.

Была проделана разумная работа по созданию стандартизированного формата JSON API .

Следование принципам этой спецификации означает, что все возвращаемые ресурсы должны фактически быть «коллекциями» (даже если включен только один ресурс). Следование этому будет означать, что ваш вызов /v1/get/moviesвернется:

{
    "movies": [
        {"name": "Ghostbusters"},
        {"name": "Indiana Jones"}
    ]
}

Ваш вызов /v1/get/books(который возвращает ноль ресурсов) вернет:

{
    "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идентификатор), а он не существует, верните a 404 Not Found.

Почему? Вы запрашиваете ресурсы . Когда вы запрашиваете коллекцию, сам ресурс (коллекция) существует. Поэтому 404неправильно. Но если вы запрашиваете определенный фильм, а он не существует, запрошенный ресурс не существует, и вы должны вернуть a 404.

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