"Новое" API к "старой" системе: архитектурные ошибки, которые мы допустили

Пропаганда инженерных практик

Тезисы

Каждый раз, когда мы готовим новую версию API или просто новый интеграционный протокол, мы попадаем в среду с типичными входными условиями:
• API нужно через неделю;
• контрагент готов с нами сотрудничать;
• "тут же чуть-чуть поправить то, что у нас есть!".

А мы, как разработка, стремимся к:
• сделать "стильно, модно, молодежно" (соответствие современным практикам);
• убрать "раздражающее" несоответствие между текущими внутренними сущностями и API;
• отгадать требования "из будущего" и заложить точки гибкости для упрощения поддержки.

За последние 1,5 года мы выпустили 2 крупных продукта, завязанных на интеграцию информационных систем нескольких компаний между собой (6 API для внешней интеграции только на нашей стороне: 4 протокола для платежей и фискализации и 2 протокола для идентификации физических лиц).

Я хочу рассказать про допущенные нами ошибки проектирования API, поделиться выводами, которые мы сделали, и лайфхаками, которые нам помогли. Я надеюсь, что наш опыт позволит вам "не пойти по нашим граблям".