Вопрос проверяет умение проектировать контрактно-ориентированный API, которым удобно пользоваться без визуального интерфейса.
API без UI проектируют как самостоятельный продукт с чётким контрактом. Важны стабильные эндпоинты, понятные форматы данных и предсказуемые ошибки. Документация должна быть частью API, а не отдельным артефактом. Версионирование и обратная совместимость критичны. Клиент не должен догадываться о бизнес-логике по косвенным признакам.
API для внешних потребителей без UI — это программный контракт, предназначенный для прямого использования другими системами без человеко-ориентированного интерфейса.
Контракт прежде реализации
Форматы запросов и ответов фиксированы.
Явные схемы данных и типы ошибок.
Предсказуемость
Одинаковое поведение в одинаковых ситуациях.
Единые правила кодов ошибок и статусов.
Версионирование
Поддержка нескольких версий API.
Запрет “тихих” breaking changes.
Явные ошибки
Машиночитаемые коды.
Чёткое описание причины и возможных действий.
Идемпотентность
Безопасные повторы запросов.
Ключи идемпотентности для write-операций.
Документация как часть API
Автогенерация спецификации.
Примеры запросов и ответов.
# POST /v1/orders
# 400 -> INVALID_INPUT
# 409 -> DUPLICATE_REQUEST
API “как для фронта”, а не для интеграций.
Неявные side-effect’ы.
Ошибки в свободной текстовой форме.
API без UI должен быть самодокументируемым, стабильным и предсказуемым, иначе его невозможно надёжно интегрировать.
