Я создал довольно простое описание API в Swagger и определил несколько объектов. Хотя сейчас я подошел к точке, в которой, я думаю, мне следует определить структуру для предоставления содержательного описания ошибки для 400+ кодов состояния, и мне также необходимо вернуть идентификаторы созданных ресурсов.
Мой API будет использоваться для связи с большими объемами и малой задержкой (в какой-то момент мне также понадобится использовать protobuf в будущей версии для дальнейшего повышения производительности). Поэтому я бы хотел, чтобы ответ был менее подробным.
Тем не менее, я склоняюсь к следующему поведению моего API:
- Возвращать простые структуры JSON без конверта для успешных запросов get
- Вернуть конверт с сообщением об ошибке, как в этом ответе, для 400+ и внутренними кодами ошибок: https://stackoverflow.com/a/12979961/1708349
- Возвращает конверт с идентификаторами для успешно созданных ресурсов (идентификаторы генерируются на сервере), таким образом, для статуса 201
Примеры * * 1016
Простой объект:
{
"smartphone_id" : "493F4756-574B-4EE2-A14C-F716B04C83AF",
"x": 10,
"y": 5
}
Сообщение об ошибке:
{
"status": "error",
"message": "Bad request: Coordinates out of bounds" /* optional */
}
Конверт для созданных ресурсов (возвращает идентификаторы):
{
"status": "success",
"message": "Smartphone object created successfully", /* optional */
"ids": ["493F4756-574B-4EE2-A14C-F716B04C83AF",
623FD344-7304-4096-9FA1-1865E96A52D9]
}
Я особенно не уверен в последнем примере, возвращающем идентификаторы для созданных ресурсов. Является ли это правильным способом обработки созданных ресурсов и смешивания API, если существует конверт для созданных ресурсов и ошибок, но не для общих данных?