API, который заставляет плакать

Чего ожидать

Цель – показать разработчикам, с какими проблемами сталкиваются пользователи их API на примере работы с различными CRM-системами.

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

Подводка

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

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

С тех пор, жил мальчик, поживал, да добра наживал. И не знал он бед и горестей… или все-таки знал? Давайте разбираться!

Я устроился в компанию, занимающуюся бизнес-аналитикой. А какая может быть аналитика без данных? Поэтому в компании была отдельная команда, а затем и отдел, который занимался сбором данных с сайтов клиентов, для построения графиков выручки с рекламных каналов и прочих источников. Если говорить о конкретике, то моя работа состояла в установке на сайты нашего счетчика, для сбора данных о посетителе, и создании заявок с форм, онлайн чатов, обратных звонков и т.д. в их CRM-системах. Из которых, в дальнейшем, наша аналитика подтягивала информацию о статусе и сумме продажи.

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

Проблема №1: недостаток методов/данных

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

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

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

Должен заметить, что у этой CRM, авторизация в API, авторизирует в том числе и в интерфейсе, что, как по мне, довольно странное решение. Впрочем, благодаря этому, нам не пришлось эмулировать обычную авторизацию. Или, так и было задумано…?

Другой случай с этой же CRM, случился не так давно. Необходимо было ставить ответственным за заявку менеджера который активен в данный момент. И как вы уже поняли, API нам не возвращает информацию об активности менеджеров. Но парадокс в том, что их JS API — возвращает. В итоге пришлось писать JS-приложение, своеобразного посредника, которой сообщал серверу об активных менеджерах в данный момент.

Решение:
У нас в команде, принято создавать для интерфейса публичный API-метод, и взаимодействовать с сервером уже через него. Это позволяет устранить проблему несоответствия технических возможностей интерфейса и публичного API.

Проблема №2: отсутствие единого стиля запросов/ответов

Очень часто встречаемая проблема даже у крупных западных CRM. Допустим нам нужно получить список заказов за месяц, мы узнаем, что у системы присутствует ограничение на кол-во элементов в выгрузке. И чтобы перемещаться по страницам нужно использовать параметр offset. Окей, мы реализовали метод загрузки заказов, и отдельно, вспомогательный метод постраничной загрузки.
Теперь, нам необходимо выгрузить список клиентов, реализовываем новый метод вместе с методом постраничной загрузки написанным ранее, и…. получаем ошибку. Потому что PM с разработчиками решили, что offset звучит слишком просто, пусть теперь это будет vid-offset.

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

Решение:
Любой новый апи-метод, по возможности, должен соответствовать структуре уже существующих. Тех.лид(или тим.лид за неимением первого) могут составить регламент, своеобразный кодстайл, по которому необходимо разрабатывать апи, и в обязательном порядке ознакомить с ним всех разработчиков. Если проблема уже имеет место быть, то при возможности, лучше поставить костыль на своей стороне, чем вынуждать это делать тысячи своих клиентов на своих сторонах.

Проблема №3: плохая документация или её отсутствие

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

В некоторых запущенных случаях, её просто невозможно найти в открытом доступе. И если нужно получить актуальный список методов — необходимо обращаться в тех.поддержку. А потом еще нужно проверить, не появилось ли там чего новенького, что у нас пару клиентов просило…

Решение:
Я приведу несколько тезисов, которые как по мне, характеризуют качественную документацию:

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

Проблема №4: авторизационные велосипеды

Вы знаете это прекрасное чувство, когда ты открываешь документацию новой системы, и там в разделе авторизации, описан порядок из 3 методов для получения ключа действительного только на 1 запрос...? Так вот, у меня его нет.

Для меня остается загадкой, почему разработчики отказываются от Oauth 2.0 в пользу своих велосипедов? И ладно, если авторизация ограничивается одним неизменным токеном, но вот целая авторизационная цепочка…

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

Эпилог

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

Так-же, благодарю всех тех, кто дочитал до сего момента! Это моя первая статья, и если она имела для вас информационную ценность, то я буду рад продолжить цикл статей, о моих страданиях с API.

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

Всех с наступившим 2020 годом!