Объекты и поиск

Все методы · Ключи и права · Ошибки

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

Для методов с ключом действуют общие проверки: 401 — ключ не принят, 403 — не хватает scope или прав владельца, 429 — превышен лимит. Неверные параметры могут дать 400, недоступный адресный ресурс — 404. Особенности команды указаны рядом с методом. Точную причину смотрите в error.code и details: как обработать ошибку и безопасно повторить запрос.

Найти записи

GET /api/v1/search

Действие ключа: search:read. Оно не заменяет права владельца на объекты и поля.

q — поисковый текст; kinds — виды сущностей через запятую; filter — JSON-фильтр поддерживаемой поиском структуры. Произвольный SQL не принимается.

Параметры пути: нет. Тело: не требуется.

Query-пример: q=VPN&page=1&pageSize=25.

Пример запроса

GET /api/v1/search?q=VPN&page=1&pageSize=25 HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Результаты поиска с информацией страницы.

{
  "data": {
    "results": [],
    "page": 1,
    "pageSize": 25
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Получить список объектов

GET /api/v1/objects

Действие ключа: objects:read. Оно не заменяет права владельца на объекты и поля.

Параметры q, typeId, state необязательны. page по умолчанию 1; pageSize 25, максимум 100. Параметр sort этот маршрут не передаёт.

Параметры пути: нет. Тело: не требуется.

Query-пример: page=1&pageSize=25.

Пример запроса

GET /api/v1/objects?page=1&pageSize=25 HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Страница доступных записей.

{
  "data": {
    "rows": [],
    "page": 1,
    "pageSize": 25
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Создать объект

POST /api/v1/objects

Действие ключа: objects:write. Оно не заменяет права владельца на объекты и поля.

Обязательны typeDefinitionId и values, содержащие все обязательные поля выбранного типа. objectId можно передать явно. Коды/форматы полей берите из metadata.

Параметры пути: нет. Тело: JSON; пример ниже показывает основные поля.

Поддерживает Idempotency-Key. См. безопасные повторы.

Пример запроса

POST /api/v1/objects HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Idempotency-Key: example-operation-001

{
  "typeDefinitionId": "TYPE_ID",
  "values": {
    "FIELD_CODE": "Значение"
  }
}

Ответ и ошибки

Успех: 201. Созданный объект.

{
  "data": {
    "id": "OBJECT_ID",
    "typeDefinitionId": "TYPE_ID",
    "revision": 1,
    "values": {
      "FIELD_CODE": "Значение"
    }
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Прочитать объект

GET /api/v1/objects/{objectId}

Действие ключа: objects:read. Оно не заменяет права владельца на объекты и поля.

Возвращаются разрешённые поля и актуальная revision.

Параметры пути: objectId. Тело: не требуется.

Пример запроса

GET /api/v1/objects/OBJECT_ID HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Объект.

{
  "data": {
    "id": "OBJECT_ID",
    "typeDefinitionId": "TYPE_ID",
    "revision": 1,
    "values": {
      "FIELD_CODE": "Значение"
    }
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Изменить объект

PATCH /api/v1/objects/{objectId}

Действие ключа: objects:write. Оно не заменяет права владельца на объекты и поля.

expectedRevision берётся из предыдущего чтения; changes содержит только изменяемые поля. При HTTP 409 перечитайте запись.

Параметры пути: objectId. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

PATCH /api/v1/objects/OBJECT_ID HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "expectedRevision": 1,
  "changes": {
    "FIELD_CODE": "Новое значение"
  }
}

Ответ и ошибки

Успех: 200. Обновлённый объект.

{
  "data": {
    "id": "OBJECT_ID",
    "typeDefinitionId": "TYPE_ID",
    "revision": 2,
    "values": {
      "FIELD_CODE": "Значение"
    }
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Архивировать объект

DELETE /api/v1/objects/{objectId}

Действие ключа: objects:write. Оно не заменяет права владельца на объекты и поля.

Это архивирование, не безвозвратное удаление. expectedRevision — текущая ревизия.

Параметры пути: objectId. Тело: JSON; пример ниже показывает основные поля.

Пример запроса

DELETE /api/v1/objects/OBJECT_ID HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "expectedRevision": 1
}

Ответ и ошибки

Успех: 200. Архивированный объект.

{
  "data": {
    "id": "OBJECT_ID",
    "revision": 2,
    "state": "ARCHIVED"
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

JSON-тело свыше 10 MiB отклоняется с 413.

Прочитать историю

GET /api/v1/objects/{objectId}/history

Действие ключа: objects:read. Оно не заменяет права владельца на объекты и поля.

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

Параметры пути: objectId. Тело: не требуется.

Пример запроса

GET /api/v1/objects/OBJECT_ID/history HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

Ответ и ошибки

Успех: 200. Массив доступных событий.

{
  "data": [],
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

Связанные статьи

• Обзор API
• Права доступа
• Интеграции