Интеграции без оверхеда: как начать, чтобы успешно закончить17.09.2020 12:48

Доступность: необходимая часть функционала может быть платной. Например, плату потребуют после 10 000 запроса к сервису — это лучше выяснить заранее и заложить в проектный бюджет.

Случай из нашей практики — с хорошим концом

Один из наших заказчиков — владелец сайта, на котором регистрируют компании в Австралии. Перед нами была поставлена задача по интеграции этого сайта с публичным австралийским государственным сервисом — ASIC Business Name Registration Service.

Первая проблема заключалась в том, что документация, размещенная на сайте сервиса, представляла собой описание функционала еще не выпущенной версии 3.1, хотя в продакшне находилась версия 1.5.

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

Он любезно предоставил соответствующую версии сервиса документацию, но на этом сложности не закончились. В ней описывались основные методы взаимодействия с сервисом в «идеальных» условиях, однако, при работе с реальными данными возникали ситуации, которых не было в документации, а сами запросы возвращали лишь »400 Bad Request» без описания причины проблемы. В каждой такой ситуации приходилось писать сотруднику саппорта и вместе искать решение. Некоторые проблемы были настолько специфичными, что он сам несколько раз обращался в свой IT-отдел за консультацией.

Третьей проблемой была разница часовых поясов между Новосибирском и Мельбурном. К тому времени, как у нас возникал вопрос к документации или по использованию сервиса, рабочий день в Австралии подходил к концу, и ответ мы получали только на следующий день утром. Вопросы возникали часто, а скорость ответов составляла приблизительно 1–2 в день.

В конечном итоге мы справились с поставленной задачей (спасибо саппортеру!), и интегрировали необходимый сервис в продукт, однако, на это ушло в ~3 раза больше времени (~300 часов против предполагаемых ~100 часов). Но, как сказал сотрудник поддержки ASIC, мы были первыми, кому это удалось.

Чек-лист при интеграции с публичным сервисом

1. Убедиться в актуальности предоставленной документации.

2. Выявить недостающую информацию заранее и уточнить детали интеграции.

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

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

Интеграция с непубличным сервисом

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

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

Случай из нашей практики — с плохим концом

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

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

Чек-лист при интеграции с непубличным сервисом

1. Если вы имеете дело с внутренним, незадокументированным сервисом, нужно запросить исходный код у владельца:

   • в случае интеграции по протоколу SOAP — запросить WSDL-файл;

   • в случае, если есть доступ к документации API сервиса (Swagger, RAML и др.) — получить доступ и изучить существующий API;

   • если есть возможность «прикрутить» систему автодокументации, то прикрутить ее и затем изучить API сервиса;

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

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

3. Если API не совсем готов, заложить календарное время на коммуникации по наполнению до требуемого уровня.

Вывод

Глобальный рынок API растет со среднегодовой скоростью 33%. В ближайшие три года этот сегмент будет занимать лидерские позиции. Уже сейчас многие сервисы успешны настолько, насколько удачно они образовали единую экосистему с другими.

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

Если же вы проводите интеграцию впервые, ищите «фонарик» или человека с «картой».

Полный текст статьи читайте на CMS Magazine