🧩 АПИ один, клиентов много

Когда мы проектируем интеграцию, легко попасть в ловушку: сделать АПИ “под конкретную систему”, а не “про свои данные”. Сегодня на другом конце провода одна CRM, завтра ее меняют, послезавтра BI переезжает на другую платформу - и каждый раз приходится переписывать контракт и пересобирать интеграцию.
Хочу поделиться парой советов, которые упрощают жизнь архитекторам и ИТ-менеджерам.

💡 Не подстраивайте АПИ под конкретную систему

АПИ должно описывать вашу предметную область, а не особенности клиента. Вместо “выгрузка для BI X” и “обработка заказа из системы Y” думайте в терминах сущностей и действий бизнеса: заказ, клиент, оплата, статус, документ. Если у вас есть “GET /orders” и “POST /payments”, то для этого АПИ принципиально все равно, кто его вызывает - 1С, скрипт на Python, коннектор DWH или новая CRM. Контракт опирается на модель бизнеса, а не на конкретную контр-систему.
Как только вы начинаете подстраивать АПИ под контрагента - “подправим структуру”, “модифицируем пару значений”, “посчитаем статус в их логике” - вы зашиваете в свой ландшафт чужую кухню. Сегодня это “пара полей”, через пару лет в АПИ оказывается логика приложения контрагента. Любое их изменение становится вашей задачей.

📦 АПИ источника - это Extract, а не весь ETL

ETL - это Extract, Transform, Load: достать данные, преобразовать, загрузить. Когда вы проектируете АПИ источника, вы чаще всего на этапе Extract. Ваша задача - сказать правду и отдать данные как есть. Не как “удобнее потребителю”, не как “лучше зайдет в отчет”, а реальное состояние в учетной системе.
Да, вы приводите даты к единому формату, поддерживаете адекватную схему для сумм и валют, фильтруете откровенный мусор и следите за безопасностью. Но все, что относится к бизнес логике потребителя и трансформации под его модель, - это уже Transform и Load, зона ответственности следующего слоя: ETL, интеграционной шины или модуля в целевой системе.

🧱 Где заканчивается ваша модель и начинается чужая

Если начать реализовывать Transform внутри АПИ, контракт привязывается к конкретной реализации на другом конце. Поменяется логика в DWH - придется менять АПИ. Поменяется структура в чужой CRM - снова придется менять АПИ. Вместо стабильного источника вы получаете живой организм, который дергают все, кому не лень.
Здоровая граница, где АПИ честно говорит, как устроены ваши данные и процессы, на языке ваших сущностей и статусов. Следующий слой берет эту правду и перекладывает под свои нужды. Если завтра вместо текущего потребителя появится другой, ему не придется просить вас переписать пол АПИ - он построит свой Transform и Load поверх стабильного Extract.

⚙️ Итоги

Для менеджера это еще и вопрос управляемости. Если договориться, что АПИ источника отвечает только за Extract, а вся “магия под заказчика” живет в отдельном слое, вы снижаете риск, что смена контрагента превратится в многомесячный проект по раскопкам древних интеграций.