Создание внутреннего каталога API с помощью Atlassian Compass
КЭТИ СИЛЬВЕР
СТАРШИЙ МЕНЕДЖЕР ПО ПРОДУКТУ, ATLASSIAN
Краткое описание
Здесь будет краткое описание
Время
Четыре минуты на прочтение. Менее 10 минут на настройку Compass.
Аудитория
Вы входите в состав команды по поставке программного обеспечения и используете API. Статья также будет полезна разработчикам, инженерам и многим другим специалистам.
Обязательные условия
- Получите Compass. Попробуйте бесплатно и начните работу за считаные минуты.
Создание точного каталога API — сложная задача
За последнее десятилетие мы отказались от больших монолитных систем в пользу микросервисов, распределенных архитектур и автономных команд. Мы получили преимущества, но и столкнулись с последствиями. Раньше типизированные компиляторы и тесты вполне успешно поддерживали слаженную работу всех частей большой базы кода. Сегодня мы упираемся в границы API и даже не можем сказать наверняка, будут ли они все совместимы друг с другом после развертывания.
Мы, конечно, знаем, что разработчики работают быстрее, а команды поставляют более качественные продукты, когда все понимают, как работают API и когда они меняются. Но дело в том, что отслеживать и поддерживать эту документацию довольно сложно.
Разные организации находятся на разных уровнях зрелости в вопросе составления карты своих служб. В одних командах переписка в Slack помогает производителям и пользователям API достичь взаимопонимания. А в других — документацию по работе API создают при запуске службы и больше никогда не обновляют. Если у вас налажены эффективные процессы или есть подходящие инструменты, то каждый API-интерфейс документируется, а информация о его изменениях автоматически доводится до сведения заинтересованных лиц.
На каком бы этапе этого пути вы ни находились, Compass — новая платформа для разработчиков от Atlassian — сможет упростить вам работу.
Централизованная документация по API в Compass
Где должна размещаться документация по API в мире микросервисов? Если мы создаем и развертываем службы по отдельности, это еще не значит, что для каждой из них нам нужен собственный сайт с документацией или файл OpenAPI, хранящийся где-то в укромном месте. Команде удобнее собрать всю эту информацию воедино и сделать ее доступной для поиска, а не тратить силы на создание реестра API.
Compass позволяет легко объединить всю документацию по API — за час, а не за неделю или квартал. Вам даже не придется каждый раз вручную загружать документацию при внесении изменений. Достаточно просто подключить систему SCM (Bitbucket, GitHub или GitLab) к Compass.
В течение нескольких минут Compass просканирует все подключенные репозитории, найдет в них файлы OpenAPI и добавит в общий каталог. Все API от всех ваших команд немедленно попадут в единое хранилище и станут доступны для поиска.
Обнаружение API и их интеграция
Представьте, что разработчик берется за заявку на создание нового процесса возврата средств. Он знает, что ему нужно найти правильный API-интерфейс для обработки возврата, но не знает, с чего начать. Во многих компаниях сотрудники задают вопрос в Slack и могут часами ждать, пока коллега с другого конца света подскажет, какой API-интерфейс использовать. В командах, работающих с системой Compass, все это можно сделать самостоятельно. Прямо в ней разработчик за несколько секунд найдет конечные точки API и все необходимые сведения. То есть разработчик быстрее получит ответ на свой вопрос, а команда, отвечающая за нужный API-интерфейс, сможет реже отвлекаться от работы.
Уведомления об изменениях в API
В мире микросервисов каждая служба развертывается автономно, и иногда о внесенных изменениях нужно оповестить пользователей. К счастью, Compass не только хранит документацию по API, но и помогает отслеживать изменения в них. Каждый раз, когда коллега выполняет слияние запроса pull, обновляющего документацию по API, Compass также обновляет свою версию документации. Таким образом, версия, которую разработчики видят в Compass, — это всегда самая актуальная версия API.
Более того, вся предыдущая информация отображается в логе изменений, и вы можете посмотреть, когда вносились наиболее важные изменения.
Когда у разработчиков есть необходимая документация, код поставляется быстрее
В недавнем опросе разработчиков API от Postman 52 % респондентов указали, что самая большая проблема при работе с API — отсутствие документации. Это замедляет разработку, усложняет адаптацию новых инженеров и снижает надежность программного обеспечения.
Если бы вам пришлось создавать собственный внутренний каталог API, это был бы грандиозный проект со множеством составляющих. Мы уже сделали всю эту работу за вас — единый центр документации будет готов через несколько минут.
Предоставьте команде необходимую информацию и посмотрите, как вырастет скорость поставки продуктов 🚀.