Один из продуктов i2crm — готовый API. Это решение, которое помогает разработчикам сторонних программных продуктов, например CRM-систем, интегрировать в свой сервис соцсети и мессенджеры. Мы много работали со сторонними API и знаем, как это бывает непросто. Зачастую возникает ощущение, что они написаны на коленке, впопыхах, десятком разных людей. Переводя эту ситуацию на знаменитую фразу киногероя, нельзя просто так взять и внедрить чужое API в свой проект.
Разработать же собственный API непросто и ресурсозатратно. Для этого нужны серверы, инфраструктура, штат специалистов, постоянные сопровождение и поддержка работоспособности продукта. Бизнес стремится к сокращению издержек и оптимизации процессов, поэтому для большинства компаний использование стороннего сервиса с публичным API — это лучшее решение.
Использование стороннего API: топ-4 проблем
Конечно, можно долго рассуждать, что публичный API — это в некотором роде «лицо» продукта, которое видят другие компании, и оно просто обязано быть приятным взору, но, увы, так бывает не всегда. Переходим к четырем часто встречающимся проблемам при использовании стороннего API. Начнем с менее распространенной.
Проблема №4: API не закрывает конкретную задачу бизнеса
Часто бывает так: читаешь документацию, и складывается впечатление, что это именно то, что нужно для выполнения задачи. Затем начинаешь изучать глубже, и приходит понимание, что один из кейсов выполняться не будет. Почему? Потому что API по своей сути — это лишь набор методов в виде простых функций. Это не готовое решение, а лишь инструмент, успешное использование которого зависит от умений разработчика.
Например, мы нашли подходящий метод для решения задачи по выгрузке чека, но обнаружили, что нет нужного параметра — времени проведенной операции. Чтобы добавить параметр, надо обращаться к компании-поставщику с просьбой. Будет ли она удовлетворена? Зависит от желания компании пойти навстречу.
К слову, наша команда старается изыскать способ, чтобы помочь клиенту даже с нестандартными и не совсем ясно сформулированными запросами.
Интересный кейс из практики i2crm:
Клиент хотел получать уведомления о проблемах на серверах по телефону, голосом. Это необычный запрос. Уведомления по email и в телеграм у нас реализованы давно, а телефония — нет. Казалось, она уже вообще никого не интересует.
Однако вызов был принят. Команда исследовала возможные пути решения, и самым логичным оказалось поискать API сервиса звонков роботами. Поскольку такие решения уже существуют (вспомним назойливые спам-звонки банков), мы решили не изобретать велосипед, а использовать готовый и гарантированно работающий. После выбора максимально подходящего API мы настроили систему мониторинга и тексты уведомлений для роботов. Так потребность клиента была удовлетворена, причем в короткие сроки и с минимальными усилиями с нашей стороны.
Проблема №3: сложность с доступом к ключам API
Некоторые сервисы «прячут» информацию о ключах доступа к API в очень необычные места. Мы находили такие ключи по ссылке, находящейся в конце пятой страницы документации. С чем это связано непонятно. Конечно, на поиски ключей тратится много времени и нервов.
Если компания предоставляет публичный API, ключи доступа должны быть легкодоступны и находиться в интуитивно понятном месте. В противном случае ситуация выглядит так: «У меня есть посылка, но я вам ее не отдам».
Проблема №2: компании-поставщики не сохраняют обратной совместимости
Что значит «сохранять обратную совместимость»? Не переименовывать и не удалять старых полей, даже когда выходит релиз новой версии API, в которой расширяются параметры и добавляются поля. Только в этом случае релиз не повлияет негативно на компании, которые используют сторонний API.
Объясним на примере. Представим, что интеграция налажена, все работает, все отлично, но в какой-то момент она ломается, летят ошибки. Начинаем разбираться, понимаем, что с нашей стороны ничего не менялось уже полгода. Смотрим на сторонний API и с удивлением обнаруживаем, что один простейший метод теперь делает совсем не то, что делал раньше. Наш код этого не знает, поэтому ожидает старое поведение. Итог: изменение одного простого метода без предупреждения сломало нам продукт.
А еще может измениться логика параметра, но не его наименование. Например, параметр, отвечающий за общую сумму покупки, после релиза становится параметром суммы покупки без учета НДС. Внешне параметр все тот же, но документация не обновлена. Итог: получаем ошибки.
Чтобы такого не возникало, необходимо тестировать интеграцию со сторонним API. Регулярный регресс, проверка всех методов и дотошность — только так можно исключить подобную ситуацию и вовремя предотвратить возможные проблемы.
Сохранение обратной совместимости — это правило хорошего тона в мире IT.
Проблема №1: расхождение описания и фактического устройства методов
Предыдущая проблема — следствие этой. Основная причина расхождений — постоянно меняющийся API и несвоевременная (а то и забытая) актуализация документации. Метод меняется, а описания устаревают и не поддерживаются. В нашей практике часто были случаи, когда мы обновляли свои сервисы и внезапно интеграция переставала работать. После обращения в техническую поддержку компании, с которой мы интегрированы, получали ответ, что метод удален, социальные сети уведомлены, но в документации ничего не поменяли. Почему? Вопрос повисал в воздухе.
Кроме того, в самом описании методов бывают ошибки. Например, в параметре указан string, а принимается только number, причем исключительно больше нуля и не дробное, или же ожидаемый код ответа не соответствует фактическому. Компании-поставщики не признают проблемы на своей стороне, из-за этого диалог затягивается, а проблема остается нерешенной.
Часто документация не включает в себя различные нюансы и ограничения: лимиты, аутентификацию, обязательность полей и т. п. Выяснить эти моменты получается только эмпирическим путем.
Разработка API не ограничена четкими стандартами или регламентами, в результате этого интерфейсы могут быть «сырыми» в исполнении. Поэтому компаниям, предоставляющим публичный API, крайне важно следить за актуальностью документации, доносить изменения не только до клиентов, но и до компаний, которые используют их API. В противном случае техническая поддержка будет из раза в раз объяснять, что именно поменяли и как оно теперь работает.
Заключение
Если вам повезет, вы никогда не столкнетесь с перечисленными проблемами, но это будет, скорее, исключением из общей тенденции. Все эти сложности объединяет, на наш взгляд, одно — непродуманность путей использования API другими компаниями.
Однако без сторонних API уже никуда. Это дешевые решения, которые обеспечивают работу огромного количества приложений. Они позволяют системам обмениваться данными, взаимодействовать, предоставлять доступ к сложным инновациям и внедрять готовые решения в свои сервисы. API — это артерии интернета, связывающие между собой сервисы компаний.
Создавая публичный API и документацию к нему, разработчики должны держать в голове ответ, для чего нужен их продукт и какие задачи поможет решить. Внешним же компаниям нужно осознавать и учитывать технические ограничения.
