API - это контракт, а не кусок кода
Почему интерфейс между системами важнее реализации за ним и что это значит для управления интеграциями.
Когда техническая команда говорит собственнику «нам нужно спроектировать API», обычная реакция - кивок и мысленная пометка отдать это инженерам. Слово звучит сугубо технически. Но решения, принятые на этом этапе, часто определяют, продержатся ли интеграции три года или потребуют дорогостоящих переписываний каждые полгода.
API - это не кусок кода. Это контракт между двумя системами - или двумя командами - о том, какие данные передаются между ними, в каком виде и по каким правилам. Как и любой контракт, его значительно сложнее изменить после того, как обе стороны начали на него полагаться.
Что на самом деле описывает контракт API
Хорошо описанный API определяет три вещи: форму запросов (что можно отправить), форму ответов (что вы получите в ответ) и правила обработки ошибок (что происходит, когда что-то идёт не так). Последнее обычно прорабатывается меньше всего - и стоит игнорирования дороже всего.
Когда команды относятся к API как к деталям реализации, а не к контракту, они случайно создают жёсткую связанность. Один сервис начинает полагаться на поле, которое никогда не было частью формального соглашения, другая команда переименовывает это поле - и интеграции начинают ломаться способами, которые сложно отследить. Та же дисциплина, которая делает внешние API стабильными, объясняет, почему внутренние интеграции должны строиться как управляемые контракты, а не неформальные связи между командами.
Почему версионирование - это бизнес-решение
Версионирование API - поддержка маршрутов v1, v2, v3 - часто воспринимается как задача по наведению порядка разработчиками. На практике это обещание совместимости: «мы не сломаем вашу интеграцию без предупреждения». Это обещание имеет цену: поддержка старых версий вместе с новыми требует времени. Но его нарушение тоже имеет цену - в виде сломанных интеграций и растерянных партнёров.
Решение о том, как долго поддерживать старые версии API и при каких условиях выводить их из эксплуатации, принадлежит не только инженерной команде, но и тем, кто владеет партнёрскими отношениями. Я видел компании, которые теряли интеграции, потому что инженеры устаревшие маршруты по срокам, о которых никто не сообщил бизнес-стороне.
Внутренние API так же важны, как внешние
Большинство разговоров о проектировании API сосредоточены на внешних API - тех, что открыты сторонним разработчикам или партнёрам. Но внутренние API, интерфейсы между вашими собственными сервисами и системами, несут те же риски.
Когда сервис выставления счетов и сервис заказов взаимодействуют через неформальный внутренний интерфейс, который никто не задокументировал как контракт, возникает та же хрупкость, что и при плохо спроектированном внешнем API. Изменения распространяются в неожиданных направлениях. Кто-то модифицирует сервис биллинга и не понимает, что три другие системы зависят от конкретного формата поля.
Признак того, что проектирование API пошло не так
Самый чёткий признак - когда изменение в одной системе требует одновременных изменений в пяти других местах, просто чтобы всё продолжало работать. Этот паттерн - скоординированные деплои, «ты не можешь выпустить это, пока другая команда не выпустит то» - обычно означает, что контракт между системами так и не был чётко определён.
Для исправления не требуется масштабная переархитектура. Требуется относиться к интерфейсу как к основному артефакту проектирования, а не к довеску к реализации.
Практическая отправная точка
Начиная любую новую интеграцию - будь то между собственными сервисами или с партнёром - я нахожу полезным сначала записать контракт на обычном языке, до написания какого-либо кода: что отправляющая сторона обещает отправить, что принимающая сторона обещает обработать, и что обе стороны договорились делать, если данные не пришли в ожидаемом виде.
Этот документ, даже если это всего страница, вынуждает провести важные разговоры заранее и экономит время, которое иначе было бы потрачено на отладку загадочных сбоев.