1 октября 2026 г.

Спросите большинство технических руководителей, сколько API работает в их организации, и вы получите лишь приблизительную оценку, а не точный ответ. Команды запускают сервисы независимо друг от друга, спецификации разбросаны по разным репозиториям, результаты тестов хранятся в том инструменте CI, который выбрала конкретная команда, а данные о работоспособности в продакшене находятся в совершенно отдельном стеке наблюдаемости. К тому моменту, когда происходит инцидент или наступает время аудита, вопрос «кто отвечает за этот API и исправен ли он?» превращается в многопоточную переписку в Slack вместо пятисекундного поиска.

Именно этот пробел призван закрыть API Catalog: единое, всегда актуальное представление всех API и сервисов, которыми владеет ваша организация — что существует, кто за это отвечает, насколько хорошо это протестировано, проходит ли оно CI и как оно на самом деле ведет себя в продакшене. В этом руководстве рассказывается, как настроить его и использовать в повседневной работе.

Что на самом деле агрегирует API Catalog

Прежде чем переходить к настройке, стоит прояснить, что именно попадает в это единое представление. API Catalog собирает четыре категории сигналов для каждого сервиса:

Владение и обнаружение — какие API существуют, где они определены и кто за них отвечает
Качество спецификаций — результаты линтинга OpenAPI/AsyncAPI и нарушения правил управления
Статус CI/CD — запуски конвейеров из GitHub Actions, GitLab CI или Jenkins, вплоть до уровня PR
Работоспособность в продакшене — p95 latency, частота ошибок, время безотказной работы и объем запросов для каждого эндпоинта

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

Шаг 1: Подключите свои исходные репозитории

Вам не нужно наполнять Catalog, вручную регистрируя каждый API — он сканирует их сам. Подключите репозиторий GitHub (или GitLab/Jenkins) к своему рабочему пространству Postman, и Postman просканирует его и подтянет то, что найдет: спецификации API, коллекции и, если вы запускаете сервисы в кластере Kubernetes, сами работающие эндпоинты.

Чтобы сделать это:

На главной странице нажмите API Catalog.
Подключите своего Git-провайдера и выберите репозитории, которые нужно просканировать. (Для этого шага вам потребуется роль администратора, так как это настраивает поток данных от сторонних коннекторов и репозиториев.)
Postman сканирует каждый подключенный репозиторий и автоматически добавляет обнаруженные API в качестве записей в Catalog.

Это именно то, что не дает Catalog превратиться в еще одну устаревшую таблицу — новые сервисы подхватываются по мере их добавления, а не через несколько недель, когда кто-то вспомнит о необходимости их зарегистрировать.

Шаг 2: Сопоставьте каждый API с его реальными средами

То, что API «работает», означает разные вещи в стейджинге и в продакшене, и API Catalog делает это различие явным с помощью системных сред (System Environments), позволяя сопоставить один и тот же API с каждым контекстом развертывания и видеть данные о работоспособности, специфичные для этого контекста, а не одно усредненное число.

Чтобы настроить это:

Откройте API в Catalog и перейдите в Service Environments.
Добавьте запись среды для каждого контекста развертывания (Staging, Production, Beta и т. д.).
Подключите каждую среду к соответствующему источнику:
Staging обычно подключается к вашему CI/CD конвейеру, показывая последние результаты прохождения тестов и любые нарушения спецификаций, внесенные в текущую ветку.
Production подключается к вашему стеку наблюдаемости через наблюдатель кластера, отображая текущую задержку p95, частоту ошибок и время безотказной работы для каждого эндпоинта.

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

Шаг 3: Прочитайте оценочную карту работоспособности (Scorecard)

Каждый сервис в Catalog получает оценочную карту работоспособности (Service Health Scorecard) — сводку результатов тестов, соответствия спецификациям и метрик шлюза в одном представлении. Вместо того чтобы вручную проверять панель мониторинга, отдельный отчет о тестировании и линтер спецификаций для каждого сервиса по очереди, вы открываете сервис, и Catalog сообщает вам всё необходимое.

Чтобы использовать её:

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

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

Шаг 4: Запрашивайте данные из Catalog с помощью Agent Mode

Как только данные начинают поступать, вам не нужно кликать по каждому сервису, чтобы найти то, что требует внимания. Postman Agent Mode может запрашивать данные из Catalog напрямую, используя естественный язык — например, спрашивая, какие сервисы недавно не прошли CI/CD тесты или какие из них возвращают ошибки в продакшене.

Типичный процесс выглядит так:

Спросите Agent Mode что-то вроде: «Какие сервисы не прошли CI за последние 24 часа?»
Agent Mode сопоставляет недавние развертывания и сбои по всем подключенным сервисам.
После этого вы можете дать ему указание предложить — или напрямую реализовать — исправление, будь то исправление проблемы со спецификацией, обновление неработающего теста или отправка исправления обратно в репозиторий через Git-интеграцию.

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

Почему это важно именно для платформенных команд

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

С API Catalog это превращается в: активность разработки, результаты тестов и сигналы продакшена, собранные в одном месте и обновляемые непрерывно. Команды, как правило, используют его как источник истины о том, какие API существуют и кто ими владеет — и как только данные о работоспособности начинают жить в том же представлении, обсуждения соглашений об уровне обслуживания (SLA) и проверки сервисов перестают требовать раунда «дайте я проверю и вернусь к вам с ответом».

Начало работы

API Catalog доступен в планах Postman Enterprise. Если в вашей организации он уже есть, начните с обзора Catalog в документации Postman — там описаны процессы регистрации API, подключения рабочих пространств и получения сигналов, от которых зависит оценочная карта. Если вы используете только запланированные мониторы сегодня, вы все равно получите базовые данные о работоспособности; подключение вашего CI-конвейера и API-шлюза — это то, что открывает доступ к данным о соответствии спецификациям и сигналам продакшена в одном представлении. Увидьте полный ландшафт API вашей организации в одном месте. Исследуйте API Catalog.