Должен ли необязательный, статически определенный ресурс, который не реализован, быть определен как 403 или 501 (или что-то еще)?

Question

У меня есть устройство, для которого я реализую HTTP API и определяю его через OpenAPI 3.0. Определены следующие пути:

/scan/inventory/start
/scan/location/start
/scan/direction/start

Этот API предназначен для работы на различных устройствах, но не все из них реализуют функцию location или direction, но все реализуют функцию inventory , Доступные функции могут быть запрошены с помощью GETing путь /scan.

Для устройства, которое не поддерживает location, моя команда валялась над кодом ошибки, чтобы вернуться, если кто-то попытается использовать его. Мы хотим предоставить полезную обратную связь, когда это произойдет, поэтому 404 кажется исключенным, тем более что путь задокументирован в нашем API. После прочтения и перечитывания RF C -7231 и различных его сводок 501 или 403 казались хорошим выбором.

Сначала «501 не реализовано» казалось хорошим выбором, но класс 5XX ошибок, по-видимому, указывает на более серьезную ошибку сервера.

Поскольку мы хотим предоставить обратную связь, «403 Forbidden» кажется хорошим и возлагает ответственность на клиента за доступ по неверному пути.

Я уверен, что часть проблемы заключается в том, что мы пытаемся использовать спецификацию (HTTP), которая не обязательно была разработана для произвольных API.

Что бы вы предложили нам сделать?

Answer 1

Это довольно просто 404.

Код состояния 404 (не найден) указывает, что исходный сервер не нашел текущее представление для целевого ресурса или не желает раскрывать, что он существует.

403 не прав, поскольку это означает, что пользователь не «авторизован» для доступа к этому ресурсу. Это подразумевает, что проблема лежит на стороне клиента. Но в этом случае просто нет ресурса.

501 не верно, поскольку это "означает, что сервер не поддерживает функции, необходимые для выполнения запроса. Это соответствующий ответ, когда сервер не распознает метод запроса и не способен поддерживать его для какого-либо ресурса ». В этом случае у сервера нет проблем с поддержкой запроса, просто ресурс не существует.

Обратите внимание, что «сервер» относится к веб-серверу . Вопрос не в том, поддерживает ли ваше приложение в целом некоторую функциональность, а в том, способен ли веб-сервер обрабатывать отправленный HTTP-запрос. Неправильно использовать коды состояния HTTP для указания такого типа высокоуровневого состояния приложения.

Также обратите внимание, что код состояния - это не просто частный контракт между вашим приложением и его пользователями. Все участники веб-стека - регистраторы, промежуточные кэши, браузеры и т. Д. c. - могут изменить свое поведение в зависимости от кода состояния. Вот почему важно зарезервировать такие вещи, как 5xx для фактических ошибок сервера.

Подводя итог, поскольку ресурс с таким URI не существует, лучший способ предоставить полезную обратную связь - вернуть 404 , Если вы хотите различать guish между функциями, которые никогда не поддерживаются, и функциями, которые просто не поддерживаются для этого устройства, вам следует использовать механизм, отличный от кода состояния. К счастью, вы хорошо начали, перечислив доступные функции на /scan.