Должно ли поле состояния в выходных данных вызова API в стиле REST быть числовым кодом или строкой?

Question

У меня есть API REST-ish, который возвращает JSON. Одним из полей вывода является status, которое указывает, успешно ли выполнен вызов. Я понимаю, что это несколько стандартно использовать числовые коды состояния, такие как

200 success
400 syntax error
401 authentication error
402 general error
404 user not found
408 timed out
500 fatal error
501 not yet implemented

Существуют ли какие-либо причины (кроме передачи немного меньшего числа байтов), чтобы использовать цифровые коды, а не более описательные символы в качестве статуса, например

success
syntax_error
auth_error
general_error
user_not_found_error
time_out_error
fatal_error
not_yet_implemented_error

Было бы полезно указать на современные прецеденты в уважаемых API.

Answer 1

Вы можете сделать их такими, какие вы хотите, при условии, что они являются стандартными (для всего вашего приложения) и задокументированы для пользы тех, кто использует веб-сервис.

Любовь к кодам состояния HTTP, таким как 404, заключается в том, что настоящий веб-сервис REST основан на HTTP-транспорте, поэтому имеет смысл использовать признанные стандарты.

Тем не менее, вы можете обнаружить, что коды состояния HTTP / 1.1 не являются точными - например, ваш «404 пользователь не найден» эквивалентен «404 не найден» - я думаю, что если смысл есть, то все в порядке .

Если вам нужно создать совершенно новые коды, стоит придерживаться групп HTTP - 2xx для приемлемых результатов, 3xx для требуемых изменений, 4xx для ошибок на стороне клиента и 5xx для ошибок на стороне сервера.