Публичный API v2

Публичный API v2 — это развитие публичного API v1, работающее и на чтение, и на запись. Он обслуживается по базовому пути /df-api/v2, использует ту же аутентификацию по ключу API и охватывает проекты, версии, содержимое РПИ (показатели, измерения, факты), справочники, таблицы фактов, фильтры верификации и связи. На этой странице описаны общие свойства версии v2 и её эндпоинты чтения; эндпоинты создания, изменения и удаления описаны на странице Операции записи в публичном API v2.

Общая информация

Свойство	Значение
Базовый путь	/df-api/v2
Аутентификация	Заголовок X-Api-Key (см. страницу Ключи API)
Доступ к данным	Чтение и запись
Область данных	Все эндпоинты ниже уровня версии привязаны к одной версии проекта
Ограничение частоты запросов	100 запросов за 60 секунд на один ключ
Форматы вывода	json (по умолчанию) и xlsx
Лицензия	Доступен только при действующей лицензии вызывающей компании

Витрины и подключения не входят в версию v2 — эти эндпоинты есть только в /df-api/v1 и описаны на главной странице раздела.

Что добавляет v2 по сравнению с v1

• Полноценные создание, изменение и удаление РПИ и модели данных наряду с эндпоинтами чтения
• Контроль доступа в разрезе проектов: ключ API разрешается в доступ его владельца к проектам, а операции записи требуют эффективной роли в проекте «разработчик» или выше
• Ограничение частоты запросов на ключ с соответствующими заголовками ответа
• Идемпотентное создание по заголовку Idempotency-Key
• Генерация SQL для показателей на эндпоинтах чтения
• Экспорт в Excel с подписанной ссылкой на скачивание на эндпоинтах чтения
• Локализованные подписи ролей в ответах управления доступом к проекту

Отличия в самом контракте:

Аспект	v1	v2
Путь к показателям	/rmd/measures	/measures
Путь к измерениям	/rmd/dimensions	/dimensions
Путь к фактам	/rmd/facts	/facts
Ключ пагинации	total_pages	totalPages
Поле id элемента (показатели, измерения, факты)	отсутствует	присутствует, первым полем
Ограничение частоты запросов	нет	100 запросов / 60 с на ключ
SQL для показателей	недоступно	?include_sql=true
Тип данных показателя в деталях таблицы фактов	data_type	display_data_type
Тип данных измерения в деталях таблицы фактов	data_type	display_data_type, а также dimension_type и formula
Тип данных факта в деталях таблицы фактов	data_type	поле отсутствует

Доступ к проектам

Ключ API наследует доступ к проектам того пользователя, которому он принадлежит:

• Эндпоинты, адресованные конкретному проекту, включая все эндпоинты в разрезе версии, возвращают 404 Not Found с кодом DF_API.PROJECT_NOT_FOUND, если у владельца ключа нет доступа к этому проекту. Факт существования проекта не раскрывается
• GET /projects возвращает только проекты, доступные владельцу ключа; недоступные проекты исключаются из страницы и из общего количества
• Эндпоинты записи требуют эффективной роли в проекте «разработчик» или выше — см. страницу Операции записи в публичном API v2

Ограничение частоты запросов

Ограничение составляет 100 запросов за 60 секунд на один ключ API. Каждый ответ содержит текущее состояние счётчика:

Заголовок	Описание
X-RateLimit-Limit	Максимальное число запросов в окне
X-RateLimit-Remaining	Оставшееся число запросов в текущем окне
X-RateLimit-Reset	Метка времени Unix, когда счётчик будет сброшен

При превышении ограничения возвращается 429 Too Many Requests с кодом RATE_LIMIT_EXCEEDED. Отклонённый запрос записывается в системный журнал.

Пагинация

Эндпоинты списков принимают те же параметры пагинации, что и в версии v1:

Параметр	Тип	По умолчанию	Описание
page	integer	1	Номер страницы, нумерация с 1
pageSize	integer	20	Максимум 100; большее значение возвращает 400 с кодом DF_API.PAGE_SIZE_EXCEEDED

В конверте ответа используется ключ totalPages:

{
  "measures": [ /* элементы */ ],
  "pagination": { "total": 42, "page": 1, "pageSize": 20, "totalPages": 3 }
}

Локализация

Ответы учитывают query-параметр language (ru или en); при его отсутствии используется заголовок Accept-Language. Локализуются только описательные текстовые значения — подписи статусов, типов, значений списков, а также подписи глобальной роли и роли в проекте в ответе управления доступом. Ключи JSON всегда на английском.

Форматы вывода

Эндпоинты чтения принимают параметр format со значениями json (по умолчанию) и xlsx. Другое значение возвращает 400 Bad Request с кодом DF_API.INVALID_FORMAT.

При запросе xlsx тело ответа содержит ссылку на сформированную книгу вместо самих данных:

{ "downloadUrl": "<подписанная ссылка на скачивание, действует 15 минут>" }

Состав книги зависит от эндпоинта:

Эндпоинт	Листы книги
Проекты, версии	Один лист со строками списка
Показатели, измерения, факты	Один лист для запрошенного типа элементов
Справочники, таблицы фактов, связи (списки и детали)	Один лист с возвращёнными строками
Детали таблицы фактов	Measures, Dimensions, Facts, Dimension Groups, Verification Filters
Полный экспорт РПИ	Measures, Dimensions, Facts, Dimension Groups, Fact Tables, Relationships

Эндпоинты чтения

В таблице ниже {v} обозначает /projects/{project_id}/versions/{version_id}.

Метод	Путь	Параметры query	Описание
GET	/projects	page, pageSize, format	Список проектов, доступных владельцу ключа
GET	/projects/{project_id}/versions	page, pageSize, format	Список версий проекта
GET	{v}/measures	page, pageSize, language, format, include_sql	Показатели версии проекта
GET	{v}/dimensions	page, pageSize, language, format	Измерения версии проекта
GET	{v}/facts	page, pageSize, language, format	Факты версии проекта
GET	{v}/dimension-groups	page, pageSize, language, format	Список справочников
GET	{v}/dimension-groups/{dimension_group_id}	language, format	Детали справочника
GET	{v}/fact-tables	page, pageSize, language, format	Список таблиц фактов
GET	{v}/fact-tables/{fact_table_id}	language, include_dependencies, format	Детали таблицы фактов
GET	{v}/relationships	page, pageSize, language, fact_table_id, dimension_group_id, format	Список связей
GET	{v}/relationships/{relationship_id}	language, format	Детали связи
GET	{v}/rmd	language, format, include_sql	Полный экспорт РПИ и модели данных
GET	/projects/{project_id}/access	language	Конфигурация доступа к проекту; описана на странице Операции записи в публичном API v2

Дополнительные параметры:

Параметр	Описание
include_sql	При значении true к каждому показателю добавляется сформированный SQL-скрипт (см. ниже)
include_dependencies	При значении true к каждому показателю таблицы фактов добавляется рекурсивное дерево зависимостей, в котором ссылки формулы разрешены до целевых показателей
fact_table_id, dimension_group_id	Ограничивают список связей указанной таблицей фактов в качестве источника или указанным справочником в качестве цели

Тела ответов повторяют аналоги версии v1, описанные на главной странице раздела, с перечисленными выше отличиями по URL и пагинации и одним добавленным полем: каждый объект показателя, измерения и факта начинается с поля id — как в эндпоинтах отдельных типов элементов, так и в полном экспорте РПИ.

id — это устойчивый идентификатор элемента в рамках версии проекта. Это то же значение, которое эндпоинты записи принимают в путях и возвращают в ответах, поэтому результат чтения можно сразу передать в последующий вызов изменения, удаления или назначения без дополнительного запроса. Поле является строкой и присутствует всегда, независимо от include_sql и language; поле row_number сохраняется для отображения и сортировки.

Показатели

GET {v}/measures

Ответ (200 OK):

{
  "measures": [
    {
      "id": "1000",
      "row_number": 1,
      "group": "Revenue",
      "block": "Sales",
      "measure_name": "Total revenue",
      "measure_description": "Gross revenue across all channels",
      "original_source_type": "Database",
      "original_source": { "connection": "Production PostgreSQL", "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "amount" },
      "display_data_type": "Numeric",
      "measure_type": "base",
      "formula": null,
      "status": "Active"
    }
  ],
  "pagination": { "total": 42, "page": 1, "pageSize": 20, "totalPages": 3 }
}

Измерения и факты возвращаются в том же конверте, с колоночной раскладкой своей таблицы РПИ.

Генерация SQL для показателей

Эндпоинты GET {v}/measures и GET {v}/rmd принимают параметр include_sql. При include_sql=true каждый элемент массива measures дополняется полем sql_code:

{
  "id": "1000",
  "row_number": 1,
  "measure_name": "Total revenue",
  "sql_code": {
    "generated_at": "2026-05-29T08:00:00.000Z",
    "sql_scripts": [
      {
        "fact_table_id": "11",
        "fact_table_name": "fact_sales",
        "sql": "SELECT SUM(amount) FROM fact_sales WHERE ..."
      }
    ]
  }
}

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

Полный экспорт РПИ

GET {v}/rmd

Возвращает полный снимок метаданных версии проекта — содержимое РПИ (показатели, измерения, факты) вместе с моделью данных (справочники, таблицы фактов, связи) — в одном ответе, а также отметку времени экспорта. Строки элементов имеют ту же форму, что и в эндпоинтах отдельных типов элементов.

Ошибки

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

{
  "message": "string",
  "originalMessage": "string",
  "statusCode": 404,
  "error": "string"
}

Поле	Описание
message	Локализованное сообщение, учитывает language и Accept-Language
originalMessage	Сам код ошибки, например DF_API.PROJECT_NOT_FOUND; устойчивый идентификатор для клиентов
statusCode	HTTP-код статуса
error	Название исключения

HTTP-коды на эндпоинтах чтения:

Код	Значение
200	Успех
400	Ошибка параметра или валидации
401	Ключ API отсутствует или некорректен
403	Заблокированная учётная запись, заблокированный IP или недействительная лицензия
404	Объект не существует или недоступен вызывающему
429	Превышено ограничение частоты запросов
500	Внутренняя ошибка сервера

Коды ошибок эндпоинтов чтения:

Код	HTTP	Описание
DF_API.INVALID_PARAMETER	400	Параметр пути или query не прошёл валидацию
DF_API.PAGE_SIZE_EXCEEDED	400	pageSize превышает 100
DF_API.INVALID_FORMAT	400	format отличается от json и xlsx
DF_API.PROJECT_NOT_FOUND	404	Проект не существует или недоступен владельцу ключа
DF_API.VERSION_NOT_FOUND	404	Версия не существует или недоступна
DF_API.DIMENSION_GROUP_NOT_FOUND	404	Справочник не существует в указанной версии
DF_API.FACT_TABLE_NOT_FOUND	404	Таблица фактов не существует в указанной версии
DF_API.RELATIONSHIP_NOT_FOUND	404	Связь не существует в указанной версии
RATE_LIMIT_EXCEEDED	429	Превышено ограничение частоты запросов на ключ

Коды ошибок аутентификации приведены на странице Ключи API, коды ошибок операций записи — на странице Операции записи в публичном API v2.