Как организовать получение списка допустимых значений параметра от API?

Question

[Евгений]

Привет

Необходимо спроектировать API.

Подскажите, каким образом передавать клиенту список возможных значений некоторых полей?

Например:
У объекта "СЧЕТ" есть свойство "СТАТУС" со значениями оплачен/частично оплачен/отменен и так далее.
[{
"id":1,
"sum": 100,
"status": "paid",
"items": [
{
"id": 1,
"name": "Пончик",
"price": 50,
"quantity": 2
}
]
}]

На клиенте должна быть сформирована HTML-форма для редактирования данных счета. Статус счета должен выбираться из списка доступных значений.

Пока вижу несколько вариантов:

1) Описать все возможные значения в документации к API. На клиенте при этом будет зафиксирован список доступных значений. Минус - при добавлении нового статуса нужно менять код клиента.
2) Предоставить API для получения списка статусов (/v1/invoices/statuses, /v1/invoices/1/statuses). Клиент отдельно загружает данные о счете и отдельно данные о статусах.

Знаете ли примеры API где каким-то образом эта ситуация решена? Расскажите о своем опыте.

Answer 1

[chromimon]

HATEOAS, Swagger, OpenAPI, OpenAPI editor, Swagger editor

Answer 2

[AlexRas]

Делаешь проверку доступности значений в апи и описываешь их в документации. Самый простой способ.