Пока систем две, интеграция — это просто обмен. Когда систем пять, начинается арифметика, о которой редко думают заранее: связей между ними становится больше, чем самих систем, и каждая связь требует сопровождения.
Почему связи растут быстрее систем
Из этого не следует, что шина нужна всем. При двух-трех системах она избыточна и только усложняет. Но при пяти и больше, особенно если системы меняются, прямые связи превращаются в клубок, где никто не знает, что сломается от изменения формата одного поля.
Что должно быть в хорошем API
Независимо от того, свой это API или чужой, работают одни и те же требования.
- Версионирование. Изменение, ломающее совместимость, выходит новой версией, старая живет какое-то время. Без этого любое улучшение останавливает работу партнеров.
- Идемпотентность. Повторный вызов с тем же идентификатором операции не создает второй заказ. Сеть рвется всегда, вопрос только в последствиях.
- Внятные ошибки. Код, машиночитаемая причина и человеческое описание. Ответ «500 Internal Error» превращает отладку в переписку.
- Ограничение частоты. Явный лимит и понятный ответ при его превышении. Иначе одна ошибка в чужом коде кладет ваш сервис.
- Постраничная выдача. Любой список рано или поздно станет большим. Отдавать сразу все — значит однажды отдать таймаут.
- Документация с примерами. Не описание полей, а рабочие примеры запросов и ответов. Экономит недели чужого и своего времени.
Отдельно про формат обмена ошибками бизнес-логики. Заказ не создан, потому что клиент в стоп-листе, — это не техническая ошибка, и возвращаться она должна не как сбой, а как понятный отказ с причиной. Смешение этих двух видов ответов — источник половины проблем на стыках.
Синхронно или через события
Выбор влияет на надежность сильнее, чем выбор протокола.
Запрос-ответ
Система А спрашивает Б и ждет ответ. Просто и понятно. Проблема в том, что А зависит от доступности Б: если Б лежит, у А тоже ничего не работает.
События и очередь
Система А кладет сообщение, Б забирает, когда может. А продолжает работать, даже если Б в обновлении. Сложнее в отладке, зато переживает сбои.
Практическое правило: то, что нужно пользователю прямо сейчас на экране, — запрос-ответ. То, что должно произойти надежно, но не обязательно мгновенно, — события.
Где здесь ИИ
Интеграции — та область, где модели помогают разработчику, а не бизнес-пользователю, и эффект от этого вполне денежный.
Разбор чужой документации. Подключение к незнакомому API начинается с чтения сотни страниц. Модель сокращает этот этап до вопросов по существу и черновика клиента.
Сопоставление форматов. У поставщика поля называются одним образом, у вас другим. Черновик правил сопоставления модель делает быстро, человек проверяет спорные.
Разбор нестандартных ответов. Часть российских сервисов отдает данные в свободной форме или в виде документов. Там, где нормального API нет, модель превращает ответ в структуру — это некрасиво, но часто единственный рабочий вариант.
Чего не стоит делать — ставить модель в разрыв рабочего обмена, где формат стабильный. Обычный код там дешевле, быстрее и предсказуем.
Безопасность обмена
Интеграции — самое незаметное место утечек, потому что про них вспоминают реже, чем про пользовательский вход.
- Отдельный ключ на каждого потребителя. Один общий ключ на всех нельзя отозвать, не сломав всем сразу.
- Минимальные права. Партнер, которому нужны остатки, не должен иметь доступ к ценам закупки. Права даются по объектам и операциям, а не целиком.
- Ротация ключей. Возможность выдать новый ключ, пока старый еще работает. Иначе смена ключа означает простой.
- Ключи вне кода. В переменных окружения или хранилище секретов, а не в репозитории.
- Журнал обращений. Кто, когда, к чему обращался. Без него инцидент не расследуется.
- Лимит на потребителя. Не только защита от нагрузки, но и сигнал о том, что на чужой стороне что-то пошло не так.
Если API делаете вы
Когда вашей системой пользуются партнеры или подрядчики клиента, к обычным требованиям добавляется несколько вещей.
- Тестовый контур. Отдельная среда с тестовыми данными, где партнер может ошибаться без последствий. Ее отсутствие превращает отладку в эксперименты на боевых данных.
- Документация с рабочими примерами. Готовые запросы, которые можно выполнить и увидеть ответ. Это сокращает подключение с недель до дней.
- Понятный порядок изменений. Как предупреждаете о новой версии, сколько живет старая, где это объявляется.
- Ответ на вопрос «почему не работает». Тот, кто подключается, должен по ответу понять, что сделал не так, без письма в поддержку.
Типичные ошибки
- Нет журнала обменов. Когда данные разошлись, восстановить, что и когда передавалось, невозможно.
- Секреты в коде. Ключи и пароли к чужим API лежат в репозитории. Обнаруживается это обычно неприятным образом.
- Нет ограничения на объем. Первая же выгрузка за год кладет и приемник, и источник.
- Ретраи без задержки. Сервис не ответил, клиент повторяет запрос пятьсот раз в секунду и добивает его окончательно.
- Интеграция без владельца. Обмен работает годами, потом ломается, и выясняется, что его настраивал подрядчик, которого больше нет.
Частые вопросы
Нужна ли интеграционная шина
При пяти и более системах с активным обменом — обычно да, и не обязательно тяжелая. Иногда достаточно брокера очередей и нескольких сервисов. При двух-трех системах шина добавляет работы больше, чем экономит.
Что делать, если у нужной системы нет API
Варианты по убыванию приличия: обмен файлами по расписанию, выгрузка из базы на чтение, работа через интерфейс программно. Последнее ненадежно и ломается при любом обновлении, но иногда альтернативы нет.
Сколько стоит интеграция
Зависит не от протокола, а от числа объектов обмена и количества договоренностей по ним. Простой односторонний обмен справочником — дни. Двусторонняя синхронизация с разрешением конфликтов — недели. Подробнее про структуру стоимости.
Разберем ваш зоопарк систем
Опишите, какие системы стоят и что между ними должно ходить. В ответ — карта обменов, где прямые связи оправданы, а где пора выносить обмен в общий контур, и оценка работ по каждому потоку.
Журнал обменов и сверка закладываются в работу сразу.