Структура API¶

С помощью Структуры API вы можете получить актуальную структуру REST API вашего приложения, построенную на основе данных о фактическом использовании API. ПО непрерывно анализирует запросы из реального трафика и формирует структуру API.

Какие задачи решает Структура API?¶

Основная задача, которую позволяет решить Структура API — получение актуальной и полной структуры API.

Построенная структура API позволяет:

• Иметь картину всего API, включая список публичных и внутренних эндпоинтов.

• Понимать, какие данные передаются в API.

• Фиксировать API, в которых на сервер передаются чувствительные данные.

• Обнаруживать список эндпоинтов, отсутствующих в вашей спецификации ("Shadow API").

• Отслеживать изменения в структуре API.

• Предоставлять разработчикам доступ к чтению построенной структуры API.

Как работает ПроAPI Структура?¶

Определение шума

• Стабильность эндпоинта – не менее 5 запросов в течение 5 минут.

• Стабильность параметра – параметр встречается более чем в 1% успешных запросов к данному эндпоинту.

• Учитываются только запросы с ответом 2xx. Стандартные поля (Content-Type, Accept) отбрасываются.

Элементы структуры API

• Эндпоинты API и методы запросов (GET, POST и др.).

• Обязательные и опциональные GET/POST параметры и заголовки.

• Тип/формат данных и наличие чувствительных данных (AI, учетные данные, финансовые, медицинские, PII, технические).

• Дату последнего обновления информации о параметре.

Типы и форматы данных:

Система определяет форматы: Int32, Int64, Float, Double, Date, Datetime, Email, IPv4, IPv6, UUID, URI, Hostname, Byte, MAC.
Если формат не определен, указывается общий тип: Integer, Number, String, Boolean.

Поиск и фильтрация эндпоинтов¶

Доступны поисковая строка и фильтры для получения специфических выборок:

• Эндпоинты, измененные за последнюю неделю и обрабатывающие чувствительные данные.

• Эндпоинты для загрузки данных на сервер (частая цель атак).

• Эндпоинты с банковскими данными клиентов.

• Эндпоинты устаревшей версии API (например, /v1).

• Эндпоинты с высоким уровнем риска.

• Эндпоинты, относящиеся к критическим бизнес-сценариям (биллинг, авторизация).

Отслеживание изменений¶

Система независимо определяет:

• Состояние эндпоинта.

• Наличие изменений в его структуре.

Для расчёта используется окно наблюдения продолжительностью 7 дней.

Состояние эндпоинта¶

Эндпоинт может находиться в одном из следующих состояний:

• Новый – впервые обнаружен в течение последних 7 дней.

• Активный – обнаружен более 7 дней назад и наблюдался в течение последних 7 дней.

• Неиспользуемый – обнаружен более 7 дней назад и не наблюдался в течение последних 7 дней.

Повторное появление ранее известного эндпоинта не делает его новым. После возобновления обращений такой эндпоинт считается активным.

Изменения структуры¶

Структура эндпоинта считается изменённой, если в течение последних 7 дней система зафиксировала хотя бы одно из следующих событий:

• В известном эндпоинте появился новый параметр.

• Параметр перестал наблюдаться, при этом обращения к самому эндпоинту продолжаются.

• У параметра изменились тип, формат или состав чувствительных данных.

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

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

Если обращения к эндпоинту прекращаются, система сохраняет его последнюю подтверждённую структуру.

Отображение статусов¶

Статус эндпоинта и изменение его структуры могут отображаться одновременно.

Таким образом, изменение структуры отображается одним из двух способов:

• Текстом «Изменённый» – для активного эндпоинта.

• Оранжевой точкой – для нового или неиспользуемого эндпоинта.

Индикатор изменения структуры¶

Оранжевая точка рядом с со статусом означает, что в течение последних 7 дней у эндпоинта было зафиксировано изменение структуры.

Фильтрация¶

Для отбора эндпоинтов используются два независимых фильтра: «Статус» и «Изменения».

Фильтр «Статус»

Позволяет выбрать состояние эндпоинта:

• Новый
• Активный
• Неиспользуемый

Фильтр «Изменения»

Позволяет выбрать состояние структуры эндпоинта:

• Изменённый – в течение последних 7 дней зафиксировано изменение структуры.

• Без изменений – в течение последних 7 дней структурные изменения не зафиксированы.

В каждом фильтре можно выбрать одно или несколько значений. Значения внутри одного фильтра объединяются по условию «ИЛИ».

Между фильтрами применяется условие «И». Эндпоинт должен соответствовать выбранным значениям обоих фильтров.

Если значение в одном из фильтров не выбрано, соответствующая характеристика не ограничивает результаты.

Публичные и внутренние эндпоинты¶

Эндпоинт считается внутренним, если располагается на частном/локальном IP-адресе или общем домене верхнего уровня (localhost и т.д.). В остальных случаях – публичный. По умолчанию отображаются все эндпоинты, но можно переключиться на просмотр только публичных или внутренних.

Вариативные элементы в эндпоинтах¶

ПроAPI Структура объединяет вариативные элементы (например, ID пользователя) в формате {parameter_X}.

Пример: /api/articles/author/author-a-0001 и /api/articles/author/author-b-1401 станут /api/articles/author/{parameter_X}.

Просмотр параметров эндпоинта¶

При нажатии на эндпоинт открывается детальная информация: имя параметра, часть запроса, тип/формат, Pattern, Ограничения, наличие чувствительных данных. Также отображается статистика: количество запросов за 24 часа, за 7 дней, RPS за 5 минут.