API-домены и семейства методов (на примере API Яндекс.Метрики)

API-домен - это логический раздел функций провайдера, объединенный общей предметной областью.

Простыми словами: это "группы возможностей", каждая из которых решает свой тип задач.

Типовая структура доменов у API-провайдера:

1. Управление ресурсами (management)

• Методы создания, изменения, удаления и настройки сущностей.

1. Получение данных и отчетов (reporting/read)

• Методы чтения агрегированных данных, статистики, списков и параметров.

1. Работа с сырыми данными или событиями (raw/logs/events)

• Методы выгрузки детализированных записей для аналитики и последующей обработки.

1. Справочники и метаданные (metadata)

• Методы получения схем, измерений, доступных полей и конфигурационных значений.

1. Служебные операции (service)

• Методы проверки доступа, состояния сервиса, версий и технических ограничений.

На примере API Яндекс.Метрики домены можно читать так:

1. management (управление объектами)

• Примеры endpoint:
• GET /management/v1/counters
• GET /management/v1/counter/{counterId}/goals

1. stat (агрегированные отчеты)

• Примеры endpoint:
• GET /stat/v1/data
• GET /stat/v1/data/bytime

1. logs (неагрегированные выгрузки; отдельный workflow)

• Пример домена выгрузок:
• /management/v1/counter/{counterId}/logrequests (инициация/контроль выгрузки)

Техническое уточнение:

• У каждого домена могут быть собственные ограничения, форматы параметров, правила пагинации и особенности авторизации.
• Разные домены часто требуют разных паттернов запросов: "часто читать", "редко изменять", "пакетно выгружать".

Практический вывод:

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