Блог

например, одним из преимуществ http REST перед SOAP является то, что REST использует машинный язык / соглашение для передачи большого значения (т. Е. http POST означает создание, http DELETE означает удаление .. и т. Д.).. таким образом, это устраняет много двусмысленности и места для ошибок, связанных с бесплатными для всех протоколами, такими как soap..

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

 get api/drivers
 

если найдены некоторые драйверы.. тогда обычно вы возвращаете json с количеством драйверов деталями и т. Д. Но что происходит, когда найдено 0 драйверов? должны ли вы возвращать данные в том же формате с 0? или вы должны использовать коды ответа http и возвращать код http 404?

хотя использование кода 404 будет соответствовать идее соглашения о конфигурации.. и позволить машинному языку выполнять большую часть интерпретации / объяснения.. я нашел некоторых инженеров, которые жалуются, что ответ 404 больше похож на генерируемое исключение, и как будто что-то пошло не так, когда совершенно нормально иметь 0 драйверов, доступных поблизости от пользователя.

Обновить:

в случае нахождения количества близлежащих водителей / ресторанов и т. Д. Ответ, Вероятно, очевиден.. но что происходит, когда вы создаете rest api, который делает предположение.. например, этот

 get api/drivers/eta
 

что означает получение eta ближайшего драйвера.. что происходит, когда вокруг нет драйверов? было бы разумнее использовать здесь 404 или вернуть обычный 200 и объяснить в теле json, что драйверов не существует?

GET Запрос к ресурсу коллекции может возвращать пустую коллекцию. Этот ответ 200 OK получен, поскольку (пустая) коллекция существует. Возврат 404 Not Found будет означать, что коллекция не существует, что не так.

Запрос:

 GET /restaurants
 

Ответ:

 200 OK
Content-Type: application/json

{
  "count": 0,
  "restaurants": []
}
 

Я рассмотрел это в главе «Теория конечных точек» в разделе «API сборки, которые вам не понравятся«, но я могу дать краткое изложение.

… итак, допустим, я получил этот вызов api, где я хочу получить количество доступных драйверов вокруг меня:

получить api / драйверы

Weeeeell, это не «вокруг вас», если вы не передадите ему некоторые координаты, поскольку он не имеет состояния, и мы не хотим, чтобы какая-то случайная фоновая логика отслеживала местоположение пользователей. Поддерживать это состояние было бы сложно и странно, поэтому давайте просто передадим его по запросу.

 GET /api/drivers?lat=Xamp;lon=Y
 

если найдены некоторые рестораны.. тогда обычно вы возвращаете json с количеством ресторанов детали и т. Д. Но что происходит, когда найдено 0 ресторанов? должны ли вы возвращать данные в том же формате с 0? или вы должны использовать коды ответа http и возвращать код http 404?

Мы перешли от водителей к ресторанам, что меня немного смутило, но чтобы ответить на более общий вопрос: пустая коллекция — это 404?

Нет! Коллекция — это ресурс (вау!), Реально существующая вещь. Если у вас есть сумка с гаечными ключами, то сумка является ресурсом в той же степени, в какой гаечные ключи являются ресурсами. Со мной?

Итак, у вас есть этот пакет с ключами. Вы предоставляете все ключи, но у вас все еще есть сумка. Или, может быть, вы только что получили пакет, а гаечные ключи еще не прибыли. Или, может быть, кто-то спросил, есть ли у вас фиолетовый гаечный ключ.

Все эти запросы вернут пустой пакет с гаечными ключами.

В принципе, GET /restaurants всегда должно быть 200 OK, до того дня, когда вы устареете и удалите концепцию ресторанов из своего API. Если ресторанов не существует, тогда все в порядке, у вас есть пустой массив ресторанов.

что происходит, когда вы создаете rest api, который делает предположение.. например, этот

получить api /drivers /eta

что означает получение eta ближайшего драйвера.. что происходит, когда вокруг нет драйверов? было бы разумнее использовать здесь 404 или вернуть обычный 200 и объяснить в теле json, что драйверов не существует?

Это будет случайная конечная точка RPC в вашем REST API, так что для начала уберите это оттуда.

Если у вас есть определенный порядок, в котором вы ожидаете увидеть прогресс драйверов, то вам не нужна эта конечная точка в произвольном стиле RPC. Что вы могли бы сделать, так это:

 GET /apis/orders/<uuid>
 

Это может очень легко иметь поле «eta» за считанные минуты, но я думаю, что другая конечная точка может улучшить это:

 GET /apis/orders/<uuid>/updates
 

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

Опять же, если обновлений нет, это просто пустой пакет обновлений.

При разработке решения учитывайте следующее: простота использования, простота реализации и обслуживания.

Что касается кодов ошибок HTTP: хотя он имеет преимущества перед определением ваших собственных кодов, его использование может помешать обычным ошибкам HTTP, что ограничивает ваши возможности для будущего использования этих журналов, таких как анализ качества, обнаружение вторжений…

Тогда вызывающая сторона должна иметь дело и различать коды ошибок HTTP и коды ошибок приложения / api. Итак, если вы получите 500, будет ли это внутренней ошибкой сервера из-за какой-то неполученной ошибки или кто-то просто запустил ее, потому что пропустил некоторые обязательные параметры. если вы получаете 404, это потому, что вы пропустили свой URI (или URL изменен) или потому, что сервер не нашел некоторые запрашиваемые вами данные, например, в приведенных выше примерах «такси не найдено»

Посмотрите на некоторые API, реализованные, такие как API Google, FB .. у них есть коды возврата, определенные в возвращаемом ответе (будь то json / xml / text …)

Во-первых, /api/drivers/eta не представляет ресурс на сервере. Мы пытаемся смоделировать его как ресурс, который не является RESTful-дизайном; но давайте предположим, что вашему бизнесу необходимо поддерживать такую конечную точку. 404 следует использовать, когда ресурс, идентифицированный по URL, не может быть найден на сервере. Таким образом, в этом случае 200 OK с пустым ответом имеет больше смысла. Или, если вы хотите, чтобы это рассматривалось как случай ошибки, вы можете использовать 422 или 400 с соответствующим сообщением в полезной нагрузке ответа

Запрос:

GET /api/drivers/eta

Ответ:

200 OK Content-Type: application / json

{ «count»: 0, «drivers»: [] }