В большинстве проектов API появляется в конце: команда пишет код, а потом «обнажает» часть методов наружу. Результат предсказуем – интерфейс повторяет внутреннюю структуру базы данных, а не потребности тех, кто будет к нему подключаться. Подход API-first переворачивает порядок: сначала команда фиксирует контракт, и только потом пишет реализацию. Контракт – договор между системами, и он первичен.

Для системного интегратора это не академическая тонкость. Когда вы связываете учётную систему заказчика с порталом госуслуг, СМЭВ или банковским шлюзом, договориться об интерфейсе нужно до того, как обе стороны начнут кодировать. Иначе интеграция превращается в череду переделок.

Контракт раньше кода

Контракт описывает методы, форматы запросов и ответов, коды ошибок и правила версионирования. Его пишут на языке, понятном машине и человеку: для SOAP это WSDL и XSD, для REST – JSON Schema и спецификация в Apiary или RAML. Главное – документ существует отдельно от реализации и согласован обеими сторонами.

Что это даёт на практике:

  • Команды работают параллельно. Поставщик API и потребитель начинают одновременно, опираясь на заглушки (mock-сервер), которые отдают данные по контракту.
  • Тесты пишутся против контракта, а не против реализации. Расхождение видно сразу.
  • Документация не устаревает, потому что она и есть исходник интерфейса.

Особенно это важно в госсекторе, где регламенты межведомственного взаимодействия меняются, а сроки подключения к СМЭВ жёстко привязаны к нормативным актам. Контракт фиксирует обязательства до старта разработки и снимает споры «кто что обещал».

Версионирование и обратная совместимость

API живёт дольше любого релиза, который его породил. Поэтому контракт сразу проектируют с расчётом на изменения. Базовое правило простое: добавлять можно, ломать – нельзя. Новое поле в ответе не должно сломать старого клиента; если меняется семантика – выпускайте новую версию (/v2/), а старую держите до тех пор, пока живы её потребители.

Это требует дисциплины. Матрицу версий и сроки их поддержки стоит фиксировать прямо в договоре на интеграцию корпоративных и государственных систем, чтобы заказчик планировал миграцию, а не узнавал об отключении старого метода постфактум.

Контракт включает безопасность

Контракт – это не только поля и методы. Это аутентификация, авторизация и обработка ошибок. Где живут ключи и токены доступа, как они ротируются, что возвращает API при истёкшем сертификате – всё это часть договора, а не деталь реализации.

Апрельская история с уязвимостью Heartbleed в OpenSSL показала цену небрежности: скомпрометированный TLS-канал обнуляет любую красивую схему обмена. Если контракт опирается на TLS и токены, в него же надо заложить процедуру их замены – мы об этом писали в заметке про ротацию секретов. Контракт, который не описывает, что делать при компрометации ключа, неполон.

Вывод

API-first – это смещение усилий на раннюю стадию, где правки дёшевы. Вы платите проектированием контракта, чтобы не платить переделками и простоями интеграции. Для корпоративных и государственных систем, которые живут годами и подключают всё новых потребителей, это не роскошь, а способ не утонуть в технологическом долге – о росте интеграционной нагрузки мы предупреждали ещё в прогнозе на 2014 год. Начинайте с договора, а код подтянется.