Все, что вы разрабатываете, не будучи зависимыми от третьих сторон, более предсказуемо по финансовым и временным затратам. При интеграции же «мяч» почти постоянно находится на стороне команды сервиса. Непрерывность хода и стоимость проекта обусловлены их уровнем вовлеченности в сотрудничество, а также состоянием документации к API.

Мы в Axmor осуществили 100+ интеграций с различными веб-сервисами и аппаратными решениями, и можем сказать, что практически каждая интеграция в плане управления проектом — это путь, полный мелких и крупных подводных камней. Тем не менее, все решаемо, вопрос лишь в количестве рисков, которые нужно учесть на старте.

В статье мы предложим 2 чек-листа действий — для случаев интеграции с публичными и непубличными сервисами. Эти подготовительные мероприятия помогут минимизировать перерасходы по времени или бюджету и спрогнозировать объем рисков в целом.

Статья будет полезна менеджерам проектов, тимлидам и разработчикам.

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

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

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

• Полнота: документация неполная и описаны не все случаи использования сервиса;

• Актуальность: фактический функционал сервиса отличается от функционала, описанного в документации;

• Стабильность: функционал на практике может оказаться нестабильным или лимитированным;

• Доступность: необходимая часть функционала может быть платной. Например, плату потребуют после 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%. В ближайшие три года этот сегмент будет занимать лидерские позиции. Уже сейчас многие сервисы успешны настолько, насколько удачно они образовали единую экосистему с другими.

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

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