Должен ли я использовать разные коды Satus в успокоительном API, вместо всего 200? - PullRequest
Новая
       9

Должен ли я использовать разные коды Satus в успокоительном API, вместо всего 200?

0 голосов
/ 03 октября 2019

Я занимаюсь разработкой сервиса RESTful API. У меня возникли разногласия между мной и моим руководителем группы по теме: «Коды статуса HTTP-ответа».

Мой руководитель группы говорит, что коды состояния HTTP по умолчанию, написанные в RFC, ужасны и с ними очень трудно справиться. их на стороне клиента (внешний интерфейс). Он считает, что пользовательские коды состояния в теле ответа с HTTP-кодом состояния 200 (каждый раз 200) - лучший способ. Его тело ответа будет выглядеть следующим образом при попытке выполнить действие без разрешений: 

HTTP/1.1 200 OK

{
    code: 1005,  // Custom code instead 403
    data: {
        message: "Forbidden."
    }

}

Я думаю, что это неправильный способ ответа. Моя схема ответа будет такой: 

HTTP/1.1 403 Forbidden

{
    code: 403,
    success: false,
    message: "Forbidden."

}

Должны ли мы использовать коды состояния HTTP RFC или мы можем использовать наши собственные настройки? Где лучший и правильный путь?

1 Ответ

1 голос
/ 03 октября 2019

Короткий

Вы абсолютно правы.

Длинный ответ

В спокойном дизайне API вы должны использовать официальные HTTP-коды, указанные в RFC-7231 . Пожалуйста, не присылайте 200 OK для каждого запроса. 200 OK зарезервировано для запросов, которые фактически выполнены, и сервер отвечает с действительным состоянием определенного ресурса. Есть коды для большинства случаев использования. Если вам все еще нужно различать ошибки одного и того же типа, например FORBIDDEN, вы можете отправить свой собственный код ошибки. Но HTTP-ответ все еще является ошибкой, поэтому вы не должны использовать 200 OK.

Что касается предложенной схемы ошибок, вы не должны отправлять код и статус в теле. Это уже отправлено как статус HTTP и поэтому избыточно. Также логический флаг успеха является избыточным, поскольку тип HTTP-кода уже указывает, был ли он успешным или нет (2xx => успех, ошибка клиента 4xx, ошибка сервера 5xx). Тело должно содержать дополнительный контекст, который поможет клиенту API решить проблему.

Хорошо разработанный ответ об ошибке API должен содержать полезную информацию для устранения возможной проблемы:

  • Идентификатор запросакоторый генерируется для каждого запроса на сервере
  • Подробное сообщение об ошибке
  • (Необязательно) Код внутренней ошибки
  • (Необязательно) Категория ошибки
  • (Необязательно) Ссылкак документации API / описанию ошибок

Пример : 

HTTP/1.1 403 Forbidden
{ 
    "requestId": "a5e5dd13-0047-4d2e-b96c-55a5031f0511", 
    "message": "You are not allowed to access this resource. Missing write permission.",
    "category": "AccessControl"
}

Если этого по-прежнему недостаточно, чтобы ваша команда поверила, что вы можете указать на некоторыехорошо спроектированные REST API:

...