Запрос и дизайн API
Какие решения нужно принять до создания API в Publisher.
Запрос и дизайн API
Новый API начинается с описания результата для Consumer. Детали WSO2, Kafka и адаптера уточняются после того, как понятны use case, контракт и ожидаемое поведение.
Паспорт API
| Поле | Содержание |
|---|---|
| Назначение | Что Consumer сможет сделать через API |
| Owner | Кто принимает продуктовые и lifecycle-решения |
| Consumers | Внутренняя система, партнёр или пользовательский канал |
| Operations | Resources и HTTP methods |
| Flow | Direct, async или orchestrated |
| Backend | Целевая система и adapter owner |
| Security | Authentication, scopes, TLS/mTLS |
| Traffic | Средняя, пиковая нагрузка и burst pattern |
| Reliability | Timeout, retry, idempotency и callback |
| Data | Классификация и чувствительные поля |
Выбор flow
- Direct — одна логически завершённая операция и один основной backend.
- Async — результат приходит позже, Consumer поддерживает callback.
- Orchestrated — требуется несколько шагов, систем, ветвление или компенсация.
Подробные критерии находятся в Интеграционных потоках.
Описать бизнес-поведение
Документируйте:
- предусловия;
- основной успешный сценарий;
- side effects и state transitions;
- downstream calls;
- ошибки и отказоустойчивое поведение;
- правила повторного запроса;
- результат, видимый Consumer.
Пишите для production incident
Описание должно позволить инженеру понять реальное поведение операции ночью во время инцидента: что уже могло выполниться, что безопасно повторить и где искать результат.
HTTP semantics
| Метод | Типичное назначение |
|---|---|
GET | Получение данных без изменения состояния |
POST | Создание ресурса или запуск операции |
PUT | Полная идемпотентная замена ресурса |
PATCH | Частичное изменение |
DELETE | Удаление или деактивация |
HTTP method не определяет sync/async route автоматически. Например, POST может вернуть результат синхронно или только принять асинхронную операцию.
Definition of Ready
API готов к реализации, когда:
- назначены API Owner и technical owner;
- согласованы Consumer и resources;
- выбран flow;
- описаны request, response и errors;
- определены security и scopes;
- согласованы idempotency, timeout и retry;
- известны backend и adapter dependencies;
- определены NFR и acceptance criteria.