Документирование интеграций и API: что зафиксировать до разработки

Документирование интеграций и API нужно сделать до разработки, а не после первого сбоя обмена. Страница должна отвечать на три вопроса: какие системы обмениваются данными, какой контракт они обязуются соблюдать и как поддержка поймет, что делать при ошибке. Если эти вопросы не зафиксированы, интеграция может работать в тестовом контуре, но быстро сломаться при версии API, изменении справочника, таймауте, повторной отправке события или смене ответственного.

Рабочий комплект включает карту интеграций, API-контракты, словарь данных, примеры запросов и ответов, правила ошибок, версии, тестовые данные, требования безопасности, наблюдаемость и runbook интеграции. Это не просто техническое приложение к ТЗ: по нему аналитик согласует смысл данных, разработчик пишет обмен, тестировщик проверяет сценарии, администратор видит настройки, а поддержка действует при сбое.

• перед оценкой проекта, где есть обмен между несколькими системами;
• до разработки публичного или внутреннего API;
• когда интеграция зависит от внешнего владельца, подрядчика или другой команды;
• если обмен влияет на деньги, статусы заказов, персональные данные, склад, документы или отчетность;
• когда нужно передать интеграцию в поддержку, а не оставить знания у разработчиков.

Для простого обмена иногда достаточно короткого API-контракта и README. Для критичной интеграции нужен полный комплект: карта, контракт, данные, ошибки, версии, безопасность, тесты и эксплуатационный порядок.

API-контракт должен быть достаточным для разработки обеими сторонами без устных уточнений. В нем фиксируют не только адрес метода, но и поведение обмена: что можно отправить, что система вернет, какие ошибки возможны, как отличить временную проблему от бизнес-отказа и как меняется контракт между версиями.

Самая частая причина проблем в интеграциях - не отсутствие метода, а разные представления о данных. Поэтому рядом с API-контрактом нужен словарь данных: что означает поле, кто владелец справочника, какие значения допустимы, как обрабатываются дубли и что делать при расхождении источников.

• Словарь данных: сущности, поля, типы, обязательность, источники истины, правила преобразования и маскирования.
• Идемпотентность: что происходит при повторной отправке одного события или запроса, какой ключ используется для дедупликации.
• Ретраи: какие ошибки можно повторять автоматически, сколько попыток допустимо, когда нужен ручной разбор.
• Тестовые данные: успешные случаи, негативные сценарии, пограничные значения, данные для проверки прав и ошибок.
• Сверка результата: где видно, что операция прошла, какие статусы должны совпасть, как исправлять частичное выполнение.

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

• Показывайте реальные названия полей и допустимые значения, а не абстрактные `field1` и `value`.
• Отдельно отмечайте поля, которые нельзя менять без новой версии контракта.
• Для ошибок указывайте действие получателя: повторить, показать пользователю, отправить в ручной разбор или эскалировать.
• Если используются файлы, очереди или webhooks, описывайте формат, размер, подтверждение получения и срок хранения.

Документация интеграции должна объяснять, как обмен защищен и как его наблюдать после запуска. Внутренний API тоже требует правил доступа: кто может вызвать метод, какие ключи или токены используются, как они ротируются, какие данные нельзя писать в логи и что делать при компрометации секрета.

Runbook нужен перед запуском, а не после первого инцидента. В нем фиксируют эксплуатационные действия: как временно отключить обмен, как повторить сообщения, где смотреть очередь, кто владелец внешней системы, какие окна работ допустимы и как уведомлять пользователей.

1. Указать контуры, адреса, владельцев и контакты эскалации.
2. Описать признаки сбоя: рост очереди, таймауты, ошибки авторизации, неверные статусы, дубли.
3. Разделить автоматические ретраи, ручной повтор и операции, которые повторять нельзя.
4. Зафиксировать порядок отключения интеграции без остановки всего бизнеса.
5. Связать runbook с мониторингом, changelog и эксплуатационной документацией.

Интеграция редко остается неизменной. Поэтому в документации нужно заранее описать, как согласуются изменения: кто владелец контракта, как уведомляют потребителей, какой период совместимости дается старой версии и где публикуются release notes. Без этого даже небольшое изменение поля может сломать отчеты, обмен заказами или обработку статусов у соседней системы.

Минимальное правило: breaking changes не выпускаются без версии, описания миграции, тестового периода и контакта владельца. Некритичные расширения можно добавлять проще, но их тоже нужно отражать в changelog и тестовых примерах.

Не каждую деталь нужно превращать в отдельный документ. Если контракт уже ведется в OpenAPI, AsyncAPI или другом согласованном формате, не надо дублировать его вручную в wiki. В wiki лучше оставить пояснение: где лежит актуальная спецификация, кто ее владелец, как согласуются изменения и какие сценарии требуют ручной проверки.

Также не стоит описывать внутреннюю реализацию метода, если она не влияет на потребителя. Для интеграционной документации важнее стабильный контракт, данные, ошибки, безопасность, версии и эксплуатационное поведение.

• описать только happy path и забыть ошибки, таймауты, частичные сбои и дубли;
• не указать владельца данных и источник истины для справочников;
• смешать бизнес-отказ и техническую ошибку в одном коде;
• не описать версии API и правила обратной совместимости;
• не подготовить тестовые данные для негативных сценариев;
• оставить поддержку без логов, корреляционного идентификатора и контактов владельцев.

Хорошая документация интеграции дает проверяемую договоренность между системами. По ней можно оценить работу, разработать обмен, протестировать ошибки, безопасно выдать доступы и передать поддержку. Если проект продолжится, та же документация станет основой для изменений API, новых потребителей, миграций и разбора инцидентов.