Как создать интеграцию с другим приложением

[ding 🔔] приходит уведомление по электронной почте. Вам только что присвоили новый билет. Строка темы гласит: «Интегрируйте наше приложение с Acme CRM». Описание билета довольно скудное — всего несколько пунктов, говорящих что-то вроде:

• Синхронизируйте встречи пользователей в Acme с нашим календарем

• Отслеживайте количество точек соприкосновения с электронной почтой и телефоном, которые пользователи имеют в Acme на нашей панели инструментов.

Вы ожидали этого. Многие компании, которые используют ваше программное обеспечение, также используют Acme CRM, и вы слышали от своих отделов продаж и поддержки, что клиенты продолжают запрашивать свои данные Acme для синхронизации с вашим приложением.

Итак... вам решать, как построить интеграцию с Acme. С чего вы вообще начинаете?

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

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

Соберите требования для вашего проекта интеграции

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

Невероятно полезно иметь ряд утверждений типа «Когда foo тогда bar». Например, «Когда пользователь в Acme CRM назначает встречу с клиентом, в нашем приложении создается событие календаря, которое содержит имя клиента, номер телефона, адрес электронной почты и время встречи». Бонусные баллы, если вы можете связать каждый шаг с соответствующей документацией по API!

Размышляя над операторами «когда foo, затем bar», вы должны задать несколько сопутствующих вопросов о том, как данные должны передаваться из одной системы в другую:

• Что запускает интеграцию? Поддерживает ли Acme такие события, как веб-перехватчики (куда они отправляют данные всякий раз, когда они были изменены) или вы должны получать данные по расписанию?

• Является ли это односторонней или двусторонней интеграцией (т. е. будет ли Acme просто отправлять данные в ваше приложение, или ваше приложение также должно отправлять данные обратно в Acme)?

• Каков формат данных, которые отправляет исходная система? JSON? XML? CSV?

• Какая информация содержится в отправляемой вам полезной нагрузке?

• Какой формат данных ожидает целевая система? Вам может потребоваться получить дополнительную информацию от других третьих сторон или других конечных точек API Acme, чтобы удовлетворить требования пункта назначения.

После того, как вы поймете, как будут передаваться данные, спросите себя, что может пойти не так, и уточните, как ваша интеграция должна вести себя в следующих распространенных ситуациях:

• Что делать с «коллизиями» данных, когда одни и те же данные отправляются дважды? Следует ли проигнорировать второй запрос, создать вторую запись или обновить («upsert») существующие данные?

• Что должно произойти, если отправлены неполные или «плохие» данные (например, событие календаря с отсутствующей датой)? Нужна ли вам «очередь недоставленных сообщений» для хранения данных, из-за которых ваша интеграция дает сбой, чтобы ваши разработчики или сотрудники службы поддержки могли проверить неверные данные позже?

• Что произойдет, если один из API не работает? Ожидается ли, что ваша интеграция сохранит данные и повторит попытку позже?

Затем выясните, насколько настраиваемой вам должна быть эта интеграция. (Иногда мне приходилось создавать «разовые» интеграции для одного клиента. Гораздо чаще мне приходилось создавать многоразовые интеграции, которые могут вести себя по-разному от клиента к клиенту и обрабатывать учетные данные каждого клиента для стороннего поставщика. приложение.)

• Как пользователи аутентифицируются в каждой системе? Есть ли у пользователей собственные учетные данные для Acme или какой-то общий ключ? Где вы собираетесь надежно хранить эти секреты?

• Что будет различаться между клиентами, для которых вы развертываете эту интеграцию? У клиентов разные конечные точки API или требования к отображению данных?

• Что нужно настроить, чтобы вы могли развернуть одну и ту же интеграцию для нескольких клиентов?

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

• Как ваши клиенты будут активировать и настраивать интеграцию? Нужно ли для этого создавать UX?

• Каковы ожидания в отношении регистрации, мониторинга и оповещения? Куда должны отправляться журналы интеграции и при каких условиях кто-то должен быть предупрежден, если интеграция столкнется с проблемой?

• Где будет жить сама интеграция? Потребуется ли вам создавать специальную инфраструктуру для размещения этой интеграции?

Как видите, краткая спецификация, такая как «Импортировать встречи пользователей в наш календарь», на первый взгляд кажется простой, но есть масса вещей, которые нужно продумать, если вы хотите тщательно построить, развернуть и поддерживать свою интеграцию.

Ознакомьтесь с тем, как работает стороннее приложение

После того, как вы обдумаете все приведенные выше вопросы и получите четкое представление о стоящей перед вами задаче, пришло время ознакомиться с задействованными сторонними приложениями. Я рекомендую войти в Acme CRM, как это сделал бы конечный пользователь. Выясните, что именно означает «назначить встречу» или «записать телефонный звонок клиенту» в контексте Acme. Это должно дать вам представление о том, как связаны различные объекты, хранящиеся в приложении.

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

Вам может быть предоставлена ​​письменная информация о том, как другое приложение будет предоставлять вам данные, но я рекомендую вам настаивать на получении реальной среды песочницы, которая, по крайней мере, отправляет поддельные данные в формате, который третья сторона утверждает, что они используют. Я встречался с множеством интеграций, когда третья сторона утверждала, что будет отправлять XML в таком-то и таком-то формате, используя вызовы REST, но сообщала вам после того, как вы построили интеграцию, что они решили записать сообщения JSON в сообщение. брокер (например, Kafka или Amazon SNS). Вы можете просто быстро изменить свой код, чтобы подписаться на ленту SNS, верно? Тестирование с реальной системой намного лучше, чем самостоятельное моделирование поддельных API и потоков сообщений.

Звучит глупо, но также обязательно войдите в свое собственное приложение, чтобы убедиться, что вы знаете, что значит «создать событие календаря» или «обновить панель инструментов». Уточните у людей, запрашивающих интеграцию, что вы понимаете, какие действия должны инициировать интеграцию и где должны отображаться данные, когда они прибудут к месту назначения.

Изучите API с помощью HTTP-клиента

Вы готовы начать возиться с API, но еще не время писать код. Взгляните на документацию для разработчиков Acme. Если у них есть спецификация OpenAPI/Swagger или WSDL, которая определяет все для их конечных точек API, вам повезло! Выясните, как работает их процесс аутентификации, какие данные отправляют их веб-перехватчики и какие данные доступны для запроса. Если вам действительно повезет, Acme предоставит клиентскую библиотеку, которую вы сможете использовать, когда придет время начинать кодирование (но не надейтесь!).

Запустите свой любимый HTTP-клиент (мне лично нравится Postman) и попробуйте выполнить несколько простых аутентифицированных запросов GET и POST к песочнице Acme CRM, к которой у вас есть доступ. Убедитесь, что сторонние документы верны и что вы действительно можете получать данные из конечной точки API назначений. Дважды проверьте, содержит ли полезная нагрузка всю информацию, необходимую для сопоставления данных с вашим приложением.

Когда у вас есть запросы к Acme CRM, работающему в Postman (или в вашем любимом HTTP-клиенте), переходите, наконец, к коду.

Время строить!

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

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