Операции записи в публичном API v2

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

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

Свойство	Значение
Базовый путь	/df-api/v2
Аутентификация	Заголовок X-Api-Key
Требуемый доступ	Эффективная роль в проекте «разработчик» или выше для записи в РПИ и модель данных; владелец проекта либо Администратор компании / Суперадминистратор для управления доступом
Объекты	Проекты, версии, показатели, измерения, факты, справочники, таблицы фактов и их состав, фильтры верификации, связи, доступ к проекту и владение проектом
Недоступно	Витрины и подключения нельзя создавать и изменять через публичный API

Каждая операция записи фиксируется в системном журнале вместе со снимком затронутого объекта до и после изменения.

Семантика методов

Метод	Значение
POST на коллекции	Создаёт новый объект и возвращает его с кодом 201 Created
POST на …/bulk	Создаёт или обновляет набор строк РПИ одним вызовом
POST на пути состава, например …/fact-tables/{fact_table_id}/measures	Назначает существующие элементы родительскому объекту и возвращает сводку по элементам, для которых операция удалась и не удалась
PUT	Полная замена: должны быть переданы все обязательные поля, а любое не переданное опциональное поле сбрасывается к значению по умолчанию или пустому значению
PATCH	Частичное обновление: изменяются только переданные поля
DELETE	Удаляет объект и возвращает 204 No Content

Требования к доступу

Запись в РПИ и модель данных требует, чтобы владелец ключа API разрешался в эффективную роль в проекте «разработчик» или выше для целевого проекта:

Ситуация	Результат
У владельца ключа нет доступа к проекту	404 Not Found, код DF_API.PROJECT_NOT_FOUND — факт существования проекта не раскрывается
Доступ владельца ключа ниже разработчика (аналитик или наблюдатель)	403 Forbidden, код DF_API.WRITE_ACCESS_DENIED
Создание проекта	Владелец ключа должен принадлежать компании

У эндпоинтов управления доступом и владением действует собственное, более строгое правило — см. раздел «Доступ к проекту и владение проектом».

Повторные запросы

Запрос POST может нести заголовок Idempotency-Key со значением в формате UUID версии 4. Ключ запоминается на 24 часа в разрезе ключа API, метода и пути, что делает повторный вызов безопасным после сбоя сети:

Ситуация	Результат
Запрос с таким же ключом уже завершился	Сохранённый ответ возвращается повторно без изменений
Запрос с таким же ключом ещё выполняется	409 Conflict, код DF_API.IDEMPOTENCY_IN_PROGRESS
Значение заголовка не является корректным UUID версии 4	400 Bad Request, код DF_API.INVALID_IDEMPOTENCY_KEY

Валидация и ссылочная целостность

• Имена должны соответствовать допустимому шаблону и быть уникальными в своей области; дубликат возвращает 409 с кодом DF_API.DUPLICATE_NAME
• Формулы показателей разбираются, а их ссылки разрешаются. Ошибка синтаксиса возвращает 422 (DF_API.INVALID_FORMULA_SYNTAX), неизвестная ссылка — 422 (DF_API.FORMULA_REFERENCE_NOT_FOUND), циклическая ссылка — 422 (DF_API.CIRCULAR_DEPENDENCY)
• Удаление или снятие назначения элемента, на который ещё есть ссылки, возвращает 409 с кодом DF_API.CONSTRAINT_VIOLATION
• У версии есть только название, признак глобальной версии и — при создании — опциональная исходная версия для копирования. Эндпоинты версий не принимают описание

Проекты и версии

Метод	Путь	Описание
POST	/projects	Создать проект: name, опционально description и color
PATCH	/projects/{project_id}	Изменить метаданные проекта
DELETE	/projects/{project_id}	Удалить проект со всем содержимым (204)
POST	/projects/{project_id}/versions	Создать версию, при необходимости скопировав существующую через clone_from_version
PATCH	/projects/{project_id}/versions/{version_id}	Изменить name или is_global версии
DELETE	/projects/{project_id}/versions/{version_id}	Удалить версию со всем содержимым (204)

Установка is_global для версии, конфликтующей с другой глобальной версией, возвращает 422 с кодом DF_API.GLOBAL_VERSION_CONFLICT.

Показатели, измерения и факты

В таблицах ниже {v} обозначает /projects/{project_id}/versions/{version_id}. Эндпоинты показаны для показателей; измерения (/dimensions, {dimension_id}) и факты (/facts, {fact_id}) работают точно так же.

Метод	Путь	Описание
POST	{v}/measures	Создать показатель
POST	{v}/measures/bulk	Создать или обновить набор показателей одним вызовом
PUT	{v}/measures/{measure_id}	Заменить показатель (полное обновление)
PATCH	{v}/measures/{measure_id}	Изменить показатель (частичное обновление)
DELETE	{v}/measures/{measure_id}	Удалить показатель (204)

Пример создания показателя:

{ "measure_name": "Total revenue", "measure_type": "base", "group": "Revenue", "formula": "SUM([Amount])" }

Эндпоинты массовых операций принимают строки в массиве, названном по типу элементов, например { "measures": [ … ] }.

Идентификаторы элементов в этих путях — это значения id, возвращаемые эндпоинтами чтения.

Справочники

Метод	Путь	Описание
POST	{v}/dimension-groups	Создать справочник
PUT	{v}/dimension-groups/{dimension_group_id}	Заменить метаданные справочника (полное обновление)
PATCH	{v}/dimension-groups/{dimension_group_id}	Изменить метаданные справочника
DELETE	{v}/dimension-groups/{dimension_group_id}	Удалить справочник (204)
POST	{v}/dimension-groups/{dimension_group_id}/dimensions	Добавить измерения в справочник
PATCH	{v}/dimension-groups/{dimension_group_id}/dimensions/{dimension_id}	Изменить уровень иерархии измерения в справочнике
DELETE	{v}/dimension-groups/{dimension_group_id}/dimensions/{dimension_id}	Удалить измерение из справочника (204)

Назначение одного и того же уровня иерархии двум измерениям одного справочника возвращает 409 с кодом DF_API.DUPLICATE_LEVEL.

Таблицы фактов

Метод	Путь	Описание
POST	{v}/fact-tables	Создать таблицу фактов
PUT	{v}/fact-tables/{fact_table_id}	Заменить метаданные таблицы фактов (полное обновление)
PATCH	{v}/fact-tables/{fact_table_id}	Изменить метаданные таблицы фактов
DELETE	{v}/fact-tables/{fact_table_id}	Удалить таблицу фактов (204)

Состав таблицы фактов:

Метод	Путь	Описание
POST	{v}/fact-tables/{fact_table_id}/measures	Назначить показатели: { "measure_ids": [ … ] }
DELETE	{v}/fact-tables/{fact_table_id}/measures/{measure_id}	Снять назначение показателя (204)
POST	{v}/fact-tables/{fact_table_id}/dimensions	Назначить измерения: { "dimension_ids": [ … ] }
DELETE	{v}/fact-tables/{fact_table_id}/dimensions/{dimension_id}	Снять назначение измерения (204)
POST	{v}/fact-tables/{fact_table_id}/facts	Назначить факты: { "fact_ids": [ … ] }
DELETE	{v}/fact-tables/{fact_table_id}/facts/{fact_id}	Снять назначение факта (204)
POST	{v}/fact-tables/{fact_table_id}/dimension-groups	Назначить справочники: { "dimension_group_ids": [ … ] }
DELETE	{v}/fact-tables/{fact_table_id}/dimension-groups/{dimension_group_id}	Снять назначение справочника (204)

Фильтры верификации таблицы фактов:

Метод	Путь	Описание
POST	{v}/fact-tables/{fact_table_id}/verification-filters	Создать фильтр для таблицы фактов
PUT	{v}/fact-tables/{fact_table_id}/verification-filters/{filter_id}	Заменить фильтр (полное обновление)
PATCH	{v}/fact-tables/{fact_table_id}/verification-filters/{filter_id}	Изменить фильтр
DELETE	{v}/fact-tables/{fact_table_id}/verification-filters/{filter_id}	Удалить фильтр (204)

Фильтры верификации версии проекта

Метод	Путь	Описание
POST	{v}/verification-filters	Создать фильтр на уровне версии проекта
PUT	{v}/verification-filters/{filter_id}	Заменить фильтр (полное обновление)
PATCH	{v}/verification-filters/{filter_id}	Изменить фильтр
DELETE	{v}/verification-filters/{filter_id}	Удалить фильтр (204)

Связи

Метод	Путь	Описание
POST	{v}/relationships	Создать связь между таблицей фактов и справочником
PUT	{v}/relationships/{relationship_id}	Заменить координаты ключей связи (полное обновление)
PATCH	{v}/relationships/{relationship_id}	Изменить координаты ключей связи
DELETE	{v}/relationships/{relationship_id}	Удалить связь (204)

Пример создания связи:

{
  "source_fact_table_id": "11",
  "target_dimension_group_id": "9",
  "foreign_key": { "db": "analytics_db", "schema": "public", "table": "fact_sales", "column": "region_id" },
  "primary_key": { "db": "analytics_db", "schema": "public", "table": "dim_geography", "column": "region_id" },
  "relationship_type": "many_to_one"
}

Поле relationship_type принимает только значение many_to_one; другое значение возвращает 400 с кодом DF_API.INVALID_RELATIONSHIP_TYPE. Вторая связь между той же таблицей фактов и тем же справочником возвращает 409 с кодом DF_API.DUPLICATE_RELATIONSHIP.

Доступ к проекту и владение проектом

Эти эндпоинты управляют доступом к проекту, который затем наследуют ключи API. В отличие от эндпоинтов РПИ и модели данных, они требуют, чтобы владелец ключа был владельцем проекта, Администратором компании или Суперадминистратором; любой другой вызывающий отклоняется с кодом 403 и кодом ошибки PROJECT.ACCESS_DENIED.

Метод	Путь	Описание
GET	/projects/{project_id}/access	Вернуть конфигурацию доступа к проекту
POST	/projects/{project_id}/access	Добавить пользователя в проект или изменить уровень доступа пользователя
DELETE	/projects/{project_id}/access/{user_id}	Удалить доступ пользователя
PUT	/projects/{project_id}/owner	Передать владение проектом

Конфигурация доступа

GET /projects/{project_id}/access

Параметры query: language.

Возвращает владельца проекта и всех пользователей, у которых есть явный доступ. Подписи ролей локализуются так же, как в таблице пользователей проекта в приложении.

[
  {
    "id": 7,
    "first_name": "Иван",
    "last_name": "Иванов",
    "email": "ivan.ivanov@example.com",
    "isOwner": true,
    "globalRole": "Администратор",
    "projectRole": "Разработчик"
  }
]

Поле	Описание
isOwner	true для владельца проекта
globalRole	Локализованная подпись глобальной роли пользователя или null, если её не удалось определить
projectRole	Локализованная подпись роли в проекте или null, если явной роли в проекте нет

Предоставление и изменение доступа

POST /projects/{project_id}/access

{ "userId": 12, "accessLevel": "developer" }

Поле	Тип	Описание
userId	integer	Целевой пользователь; должен существовать и принадлежать компании проекта
accessLevel	string	Одно из значений developer, analyst, viewer

Если у пользователя уже есть доступ, уровень изменяется; иначе доступ предоставляется. Уровень доступа выше глобальной роли пользователя отклоняется.

Удаление доступа

DELETE /projects/{project_id}/access/{user_id}

Удаляет явный доступ целевого пользователя. Пользователь должен существовать.

Передача владения

PUT /projects/{project_id}/owner

{ "newOwnerId": 12 }

Новый владелец должен существовать, принадлежать компании проекта и иметь роль, допустимую для владения проектом — Менеджер проекта, Администратор компании или Суперадминистратор.

Правила валидации

Условие	HTTP	Код
accessLevel отсутствует или не равен developer, analyst либо viewer	400	PROJECT.INVALID_ACCESS_LEVEL
accessLevel равен project_manager — этот уровень наследуется владельцем и не назначается	400	PROJECT.ACCESS_LEVEL_NOT_ASSIGNABLE
Запрошенный уровень превышает глобальную роль целевого пользователя	400	PROJECT.CANNOT_ELEVATE_ACCESS
Целевой пользователь не существует или принадлежит другой компании	404	USER.NOT_FOUND
У нового владельца нет роли, допустимой для владения проектом	400	PROJECT.INVALID_OWNER
Вызывающий не является ни владельцем проекта, ни администратором	403	PROJECT.ACCESS_DENIED

Коды ошибок операций записи

Код	HTTP	Описание
DF_API.MISSING_REQUIRED_FIELD	400	Отсутствует обязательное поле, например при полной замене методом PUT
DF_API.INVALID_ENUM_VALUE	400	Значение поля со списком значений не входит в число допустимых
DF_API.ID_MISMATCH	400	Идентификатор в теле запроса не совпадает с идентификатором в пути
DF_API.INVALID_RELATIONSHIP_TYPE	400	relationship_type должен быть равен many_to_one
DF_API.INVALID_IDEMPOTENCY_KEY	400	Idempotency-Key не является корректным UUID версии 4
DF_API.INVALID_API_KEY	401	Не удалось проверить ключ API
DF_API.WRITE_ACCESS_DENIED	403	Эффективная роль владельца ключа в проекте ниже разработчика
DF_API.RESOURCE_NOT_FOUND	404	Целевой элемент или назначение не существует
DF_API.DUPLICATE_NAME	409	Элемент, проект или версия с таким названием уже существует в этой области
DF_API.DUPLICATE_RELATIONSHIP	409	Связь между этой таблицей фактов и этим справочником уже существует
DF_API.DUPLICATE_LEVEL	409	Двум измерениям одного справочника назначен одинаковый уровень иерархии
DF_API.CONSTRAINT_VIOLATION	409	На элемент ещё есть ссылки, его нельзя удалить или снять его назначение
DF_API.IDEMPOTENCY_IN_PROGRESS	409	Запрос с тем же значением Idempotency-Key ещё выполняется
DF_API.INVALID_FORMULA_SYNTAX	422	Не удалось разобрать формулу показателя
DF_API.FORMULA_REFERENCE_NOT_FOUND	422	Формула показателя ссылается на несуществующий элемент
DF_API.CIRCULAR_DEPENDENCY	422	Формула показателя создаёт циклическую ссылку
DF_API.GLOBAL_VERSION_CONFLICT	422	Нельзя установить is_global — конфликт с другой глобальной версией

Тело ошибки такое же, как у эндпоинтов чтения — см. страницу Публичный API v2.