API-пайплайн: связать две карточки отношением

Индекс: API-пайплайны — индекс

Цель: связать две карточки именованным отношением («поставляет», «работает с», «часть чего-то») и читать отношения и другие связи карточки.

Отношение — это ребро source → target с меткой-рубрикой (rel). Заголовок рубрики читает ребро в прямом направлении, её inverse_title — в обратном; directed: false обозначает симметричную метку. Рубрики: API-пайплайн: рубрики для карточек

Шаги

1. Выберите или создайте метку. Подходит любая рубрика, которую вы можете читать. Своя:

POST /v0/my/rubrics
Idempotency-Key: rel-label-1
{"title": "supplies", "inverse_title": "is supplied by"}
→ {"nonce": "470000000000000090", "card_type": "rubric", …}

2. Свяжите.

POST /v0/my/relations
Idempotency-Key: rel-5c0e…
{"source": "470000000000000001", "target": "470000000000000002", "rel": "470000000000000090"}
→ {"created": true,
   "relation": {"nonce": "470000000000000095", "rel": "470000000000000090",
                "source_nonce": "470000000000000001", "target_nonce": "470000000000000002",
                "direction": "out", "directed": true, "title": "supplies", "inverse_title": "is supplied by",
                "label": "supplies", "mine": true, "created_at": "…",
                "card": {"card_type": "project", "nonce": "470000000000000002", "title": "…", …}}}

• Нужно право записи на source; target и rel достаточно иметь возможность читать.
• Те же source, target и rel повторно возвращают существующее ребро с "created": false.

3. Прочитайте отношения карточки.

GET /v0/graph/relations?card=470000000000000002&dir=both&limit=50
→ {"relations": [{"nonce": "470000000000000095", "direction": "in", "label": "is supplied by", "card": {…the other card…}, …}],
   "next_before": null}

• card (обязательно): карточка, отношения которой нужны. dir: out, in или both (по умолчанию). rel: только одна метка. limit: по умолчанию 50, максимум 200. Следующая страница: before=<next_before>.
• Сначала новые. Возвращаются только отношения, у которых вы можете видеть обе карточки и метку; анонимные вызовы видят публичные.
• label — заголовок в том направлении, в котором вы читаете; mine отмечает рёбра, созданные вами.

4. Удаление. DELETE /v0/my/relations/{relation nonce} → 204. Может автор ребра или тот, у кого есть право записи на source и кто видит ребро.

Другие связи ваших карточек

GET /v0/graph/my/edges?kind=mention&target_nonce=470000000000000002&limit=100
→ {"edges": [{"kind": "mention", "source_type": "article", "source_nonce": "…", "target_nonce": "470000000000000002", …}], "total": 3}

• kind (обязательно): containment (рабочее пространство → карточка), mention (текст карточки ссылается на другую), anchor (карточка → её проект), rubric (дерево рубрик), tag (карточка → рубрика).
• Нужен один из source_nonce / target_nonce; source_type, target_type, field сужают выборку; limit 1–500 (по умолчанию 100), offset.
• Показывает связи ваших собственных карточек. Страница карточки (GET /v0/my/<type>/{nonce}) уже содержит её карточки mentioned и contained.

Что происходит за кадром

• Ничего асинхронного: отношение существует сразу, как только вызов ответил.

Правила

• 400: source must be a numeric nonce (так же для target, rel), source and target must differ, нет Idempotency-Key; dir must be out|in|both.
• 404: у вас нет права записи на source, target или rel недоступны для чтения, или rel не рубрика.
• /v0/graph/my/edges: 400 при неизвестном kind, source_nonce or target_nonce is required.

Поверхность API