Связи

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

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

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

Прочитать связи

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

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

direction=incoming выбирает входящие связи; по умолчанию outgoing. Учитываются права на связанные записи.

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

Query-пример: direction=outgoing.

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

GET /api/v1/objects/OBJECT_ID/relations?direction=outgoing HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

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

Успех: 200. Массив связей.

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

Найти доступные виды связей

GET /api/v1/relation-definitions

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

sourceObjectId необязателен. При передаче фильтрует определения по типу исходной записи; проверяет relation.create.

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

Query-пример: sourceObjectId=OBJECT_ID.

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

GET /api/v1/relation-definitions?sourceObjectId=OBJECT_ID HTTP/1.1
Host: service.example.invalid
Authorization: Bearer YOUR_API_KEY

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

Успех: 200. Массив определений.

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

Связать записи

POST /api/v1/objects/{objectId}/relations

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

definitionId должен быть активным; источник — objectId в URL. targetObjectId — вторая запись. Проверяются типы, направление, кардинальность и права.

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

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

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

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

{
  "definitionId": "DEFINITION_ID",
  "targetObjectId": "TARGET_ID"
}

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

Успех: 201. relation и признак существующей связи idempotent.

{
  "data": {
    "relation": {
      "id": "RELATION_ID",
      "revision": 1
    },
    "idempotent": false
  },
  "meta": {
    "correlationId": "CORRELATION_ID",
    "apiVersion": "v1"
  }
}

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

Убрать связь

DELETE /api/v1/relations/{relationId}

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

expectedRevision — ревизия самой связи. Дополнительные ограничения связанного поля могут запретить удаление.

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

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

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

{
  "expectedRevision": 1
}

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

Успех: 200. Архивированная связь.

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

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

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

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