API Design Standard

API представляет стабильную бизнес-возможность, а не внутреннее устройство WSO2, Kafka или целевой системы.

Ресурсы и paths

• используйте существительные и понятную иерархию ресурсов;
• lowercase paths без технических имён компонентов;
• HTTP method отражает semantics операции;
• filtering, sorting и pagination оформляются единообразно;
• action endpoints допускаются только когда resource semantics недостаточна.

Контракт данных

• JSON fields используют camelCase;
• обязательность и nullable указываются явно;
• money передаётся строкой;
• timestamps содержат timezone;
• неизвестные response fields не должны ломать Consumer;
• sensitive fields отмечаются в design и не попадают в examples/logs.

Versioning

Версия является частью публичного контракта. Breaking change выпускается как новая major version. Additive change может оставаться в текущей версии при tolerant readers.

Breaking examples:

• удаление или переименование поля;
• изменение типа или semantics;
• новый обязательный request field;
• сужение допустимых значений;
• изменение authentication или error contract.

Error contract

Ошибки должны быть стабильными и пригодными для автоматической обработки:

Не возвращайте stack traces, SQL, internal hostnames или secrets.

Pagination и retry

Для списков определите cursor/offset model, стабильную сортировку и максимальный page size. Для write-операций явно укажите, можно ли повторять запрос и требуется ли Idempotency-Key.

API checklist

• назначение понятно без знания backend;
• OpenAPI валиден;
• auth и scopes задокументированы;
• success/error cases полны;
• compatibility оценена;
• NFR измеримы;
• owner и lifecycle определены.