Примеры типов контента для ошибок проверки POST?

Question

Предположим, что HTTP-сервер отвечает на POST с кодом ответа 400, потому что запрос не прошел проверку (например, адрес электронной почты не найден). Если сервер хочет предоставить клиенту дополнительную информацию о характере ошибки, как это нужно вернуть? Для каждого возможного типа контента, используемого в запросах, должно ли в идеале быть связанный тип содержимого «ошибка»?

Например, если запрос

POST /users 
Content-Type: application/x-myuser 

{ 
    "email": "foo@example.com", 
    "name": "Michael" 
} 

ответ может быть

400 Bad Request 
Content-Type: application/x-myuser-error 

{ 
    "email": "Email address foo@example.com not found" 
} 

Есть ли какие-нибудь хорошие примеры «ошибок» типов контента в открытом доступе?

Answer 1

У меня нет никаких примеров, но это хорошо, чтобы всегда держать это в виду:

• Всегда включайте ошибку машиночитаемой и обобщать как можно больше. Структура JSON как

  {"error":"Email address not found!","code":"fielderror","field":"email","reason":"notfound"} (может быть упрощена до {"error":"...","code":"emailnotfound"})

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

• Другой подход состоит в том, чтобы просто не возвращать тело и использовать HTTP-заголовки, чтобы сообщить пользовательскому агенту, что пошло не так. Например, вы можете использовать X-Error и X-Error-Code, чтобы показать читаемую человеком ошибку и машиночитаемый код.
• Создание слишком большого количества типов контента может быть плохой. Я лично предпочитаю всегда использовать application/json и дать агенту знать статус, просматривая коды HTTP: 200, 400, 403, 404, 500 и т. Д.
• Определенно никогда не начинайте создавать комбинации HTTP-кодов и контента типы. Вы не хотите, чтобы ваши пользователи узнали, что application/myapp/error означает, что есть ошибка, ЕСЛИ это 200, в этом случае вы находитесь на экране редактирования, или когда это 302, это не ошибка, а перенаправление. Вот почему вы, вероятно, должны придерживаться одного типа контента.

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