Pipeline de API: unir dos tarjetas con una relación

Índice: Pipelines de API — índice

Objetivo: unir dos tarjetas con una relación con nombre («suministra», «trabaja con», «parte de») y leer las relaciones y otras aristas de una tarjeta.

Una relación es una arista source → target etiquetada con una rúbrica (rel). El título de la rúbrica lee la arista hacia delante, su inverse_title hacia atrás; directed: false marca una etiqueta simétrica. Rúbricas: Pipeline de API: etiquetar tarjetas con rúbricas

Pasos

1. Elige o crea la etiqueta. Cualquier rúbrica que puedas leer. Una propia:

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

2. Unir.

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": "…", …}}}

• Necesitas escritura sobre source; target y rel solo tienen que poder leerse.
• El mismo source, target y rel otra vez devuelve la arista existente con "created": false.

3. Leer las relaciones de una tarjeta.

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 (obligatorio): la tarjeta cuyas relaciones quieres. dir: out, in o both (por defecto). rel: una sola etiqueta. limit: por defecto 50, máximo 200. Página siguiente: before=<next_before>.
• Las más recientes primero. Solo se devuelven las relaciones cuyas dos tarjetas y etiqueta puedes ver; las llamadas anónimas ven las públicas.
• label es el título en la dirección en que lees; mine marca las aristas que creaste tú.

4. Quitar. DELETE /v0/my/relations/{relation nonce} → 204. Puede hacerlo el autor de la arista o quien tenga escritura sobre source y pueda ver la arista.

Otras aristas de tus tarjetas

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 (obligatorio): containment (espacio de trabajo → tarjeta), mention (el texto de una tarjeta enlaza otra), anchor (tarjeta → su proyecto), rubric (árbol de rúbricas), tag (tarjeta → rúbrica).
• Hace falta uno de source_nonce / target_nonce; source_type, target_type, field acotan; limit 1–500 (por defecto 100), offset.
• Lista las aristas de tus propias tarjetas. La página de una tarjeta (GET /v0/my/<type>/{nonce}) ya trae sus tarjetas mentioned y contained.

Detrás

• Nada asíncrono: la relación existe en cuanto responde la llamada.

Reglas

• 400: source must be a numeric nonce (igual para target, rel), source and target must differ, falta Idempotency-Key; dir must be out|in|both.
• 404: no puedes escribir en source, target o rel no se pueden leer, o rel no es una rúbrica.
• /v0/graph/my/edges: 400 con un kind desconocido, source_nonce or target_nonce is required.

Superficie de la API