Как обрабатывать типы данных ошибок и ответные сообщения в дизайне RESTful API
Я создаю свой первый RESTful API для практики и обучения. Я использую RAML и буду реализовывать это с помощью MuleSofts AnypointStudio. Я действительно не знаю, как поступать с ответами, особенно с ошибками. Мне удалось выяснить, какие коды состояния HTTP мне нужны для моих ответов, но не удалось понять, как обрабатывать ответные сообщения.
Нужно ли мне определять тип данных ответа и пример сообщения для каждого кода ответа (200, 201, 204, 404 и т. д.)? Если у меня может быть один тип данных и один пример сообщения, как мне их соответственно использовать?
В настоящее время я определил один тип ошибки и один пример сообщения.
Error.raml
#%RAML 1.0 DataType
type: object
description: This general error structure is used throughout this API.
properties:
code:
type: integer
minimum: 400
maximum: 599
description?:
type: string
default: "Bad query parameter [$size]: Invalid integer value [abc]"
example: The server understood the request, but is refusing to fulfill it
reasonPhrase?:
type: string
examples:
example: Bad Request
example1: Forbidden
example: !include ../examples/error_example.json
error_example.json
{
"code": 400,
"description": "Bad query parameter [$size]: Invalid integer value [abc]",
"reasonPhrase": "Bad Request"
}
Как видите, у меня есть переменные как в типе данных, так и в примере сообщения. Они были созданы Рестлетом. Я пока не знаю, как их использовать, поэтому просто оставил их на время.
Был бы очень признателен за любую помощь и советы.
Ответы 1
Do I need to define response datatype and example message for every response code (200, 201, 204, 404 etc.)? If I can have one datatype and one example message, how do I do use them accordingly?
Нет, не знаешь. Для ресурса вы можете указать такие ответы, как 200 или 404 (это наиболее часто используемые)
Из документов:
resourceTypes:
collection:
description: Collection of available songs in Jukebox
get:
description: Get a list of songs based on the song title.
responses:
200:
body:
application/json:
post:
description: |
Add a new song to Jukebox.
queryParameters:
access_token:
description: "The access token provided by the authentication application"
example: AABBCCDD
required: true
type: string
body:
application/json:
type: song
responses:
200:
body:
application/json:
example: |
{ "message": "The song has been properly entered" }
Пример ресурса с ошибкой не найден:
collection-item:
description: Entity representing a <<resourcePathName|!singularize>>
get:
description: |
Get the <<resourcePathName|!singularize>>
with <<resourcePathName|!singularize>>Id =
{<<resourcePathName|!singularize>>Id}
responses:
200:
body:
application/json:
404:
body:
application/json:
example: |
{"message": "<<resourcePathName|!singularize>> not found" }
Об этом есть отличный Сообщение блога. Взгляните на RAML учебные пособия, так как у них есть хорошие документы. Вы также можете взглянуть на swagger для большего «вдохновения».
Я хочу дождаться дополнительных ответов, если все в порядке. Я отмечу его как ответ через несколько дней, если больше не будет ответов
Это то, что я искал. Я надеялся, что есть способ создать один тип данных или схему (с переменными?) Для сообщений об ошибках и повторно использовать их соответственно для каждого ответа об ошибке. Но это нужно сделать, спасибо