API и интеграции

Что входит в эту категорию

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

Первые три задачи нужны командам, которые выпускают API. Четвёртая нужна всем, кто сшивает купленные инструменты. Обе аудитории оказываются на этой полке, поэтому продукты так не похожи друг на друга.

Чисто визуальная автоматизация без кода относится к no-code и автоматизации. Оповещения о работающем сервисе это мониторинг.

Клиенты и то, чем они теперь различаются

Любой клиент отправляет запрос и показывает ответ. Различия глубже.

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

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

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

Документация, которая не гниёт

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

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

Журнал изменений важнее дизайна. Потребителям нужно знать, что сломалось и когда, и никакое оформление этого не заменит.

Шлюзы и когда они оправданы

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

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

Что считают тарифы

• Места у клиентов и продуктов для документации, иногда бесплатные для рецензентов только с чтением.
• Задачи или запуски у платформ интеграций, считаемые за шаг, а не за процесс.
• Вызовы или трафик у шлюзов, с отдельной ставкой для всего, что берётся из кэша.
• Хранение истории запусков: на начальных тарифах оно короткое и заканчивается ровно тогда, когда нужно.
• Коннекторы, причём премиальные спрятаны на тариф выше того, что вам назвали.

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

Что проверять

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

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

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

Документация, версии и сохранение потребителей

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

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

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

Затем прочитайте собственную документацию глазами новичка. Самое быстрое улучшение обычно это работающий пример в начале страницы вместо справочной таблицы.