Pipeline de API: etiquetar tarjetas con rúbricas

Índice: Pipelines de API — índice

Objetivo: etiquetar tus tarjetas con rúbricas, crear tu propio árbol de rúbricas y explorar las rúbricas públicas.

Una rúbrica es una tarjeta (card_type: rubric). El tipo tag clasifica tarjetas; el tipo place es un nodo geográfico (rub.geo-…) y se asigna como location de una tarjeta, nunca como etiqueta. Las rúbricas forman árboles: una rúbrica contiene sus subrúbricas, en orden.

A. Explorar las rúbricas públicas

1. Raíces.

POST /v0/search/graph/keyword
{"query": "", "card_type": "rubric", "filters": {"roots_only": true}, "limit": 50}
→ {"hits": [{"card_type": "rubric", "nonce": "447697459225821184", "handle": "rub.iab", "title": "IAB Taxonomies", "kind": "tag", …},
            {"nonce": "447799256720343040", "handle": "rub.isic", "title": "International Standard Industrial Classification (ISIC Rev.4)", …}, …]}

2. Hijas.

GET /v0/graph/rubrics/@rub.iab?contained_limit=200&contained_offset=0
→ {"nonce": "447697459225821184", "kind": "tag",
   "contained": [{"card_type": "rubric", "nonce": "…", "title": "Automotive"}, …],
   "contained_next_offset": 200}

Pagina con contained_offset hasta que contained_next_offset sea null. Buscar una rúbrica por palabra: {"query": "dental", "card_type": "rubric", "filters": {"kind": "tag"}} en la misma búsqueda.

3. Tarjetas bajo una rúbrica. Busca con un filtro de rúbrica: "filters": {"rubrics": [["<rubric nonce>"]]} (listas internas O, externa Y; rubrics_not excluye).

B. Etiquetar una tarjeta

Las rúbricas son un campo de la tarjeta. Envía la lista completa al crear o en el PATCH; sustituye a la anterior. Cada rúbrica que añade la nueva lista requiere el derecho a marcar con ella (B3); las que la tarjeta ya tiene se quedan.

PATCH /v0/my/articles/470000000000000042
{"rubrics": ["<rubric nonce>", "470000000000000077"], "location": "<place nonce>"}

• Tarjetas que aceptan rúbricas: project, article, post, board, doc, sheet, workspace, coupon, room.
• primary_rubrics (opcional): las que se muestran primero; como mucho 2 por árbol. Sin él, las primeras de cada árbol son las principales.
• location: una rúbrica de lugar; "" la borra. Encuéntrala con GET /v0/search/geo/cities?q=… y luego GET /v0/graph/resolve/@rub.geo-<geonameid>.
• rubrics: [] quita todas las etiquetas.

B2. Marcar una tarjeta: añadir y quitar en una sola llamada

Cambia algunas rúbricas de una tarjeta sin reenviar toda la lista.

PATCH /v0/my/cards/470000000000000042/rubrics
{"add": ["470000000000000081"], "remove": ["470000000000000090"]}
→ {"nonce": "470000000000000042", "card_type": "article",
   "rubrics": ["470000000000000081", "…"], "added": ["470000000000000081"],
   "removed": ["470000000000000079", "470000000000000090"],
   "transitions": [{"parent": "470000000000000078", "from": "470000000000000079", "to": "470000000000000081"}]}

• Funciona en cualquier tarjeta que acepte rúbricas, si puedes editarla. Las rúbricas que no indicas se quedan como están.
• La respuesta muestra solo las rúbricas que puedes leer.

Árboles de etapas. Pon exclusive_children: true en una rúbrica tuya (al crear o con PATCH) y aceptará un solo hijo a la vez en cada tarjeta: añadir un hijo reemplaza al hermano que la tarjeta tenía. Úsalo para etapas, p. ej. Nuevo → Contactado → Ganado: una llamada por movimiento, se permiten saltos. transitions lista cada movimiento por árbol (from: null: la tarjeta entró en el árbol; to: null: salió de él).

Historial. Cada marca queda registrada como un cambio: qué se añadió y qué se quitó, los movimientos de etapa, quién lo hizo y cuándo.

B3. Quién puede marcar con una rúbrica

Añadir una rúbrica a una tarjeta requiere el derecho a marcar con esa rúbrica. Quitar una rúbrica nunca lo requiere.

• Tus propias rúbricas: siempre puedes marcar con ellas.
• La rúbrica de otra persona: puedes marcar con ella cuando está abierta para marcar (su propio permiso de ejecución, para todos los que pueden leerla), o cuando su dueño la compartió contigo con ejecución, mediante una concesión o un enlace de acceso emitidos sobre esa misma rúbrica. El acceso a una rúbrica padre o a un espacio por encima de ella no cuenta: cada rúbrica decide por sí misma. Las taxonomías públicas compartidas están abiertas para marcar.
• Las rúbricas nuevas empiezan cerradas (ejecución desactivada): solo tú marcas con ellas. Para abrir una a todos los que pueden leerla: PATCH /v0/my/rubrics/{nonce} {"permissions": {"read": true, "write": false, "execute": true}} (una rúbrica Unlisted o Public; una Private sigue siendo solo tuya). Para abrirla a personas o agendas concretas, compártela con ejecución: Pipeline de API: compartir tarjetas con enlaces de acceso
• Solo se comprueba lo que añade un cambio. Las rúbricas que la tarjeta ya tiene se quedan al guardarla de nuevo. El mismo derecho se necesita para una nueva location y para la rúbrica padre cuando colocas una rúbrica debajo de ella.
• can_mark (true / false, solo con sesión iniciada) te lo dice antes de intentarlo: en la página de una rúbrica (GET /v0/graph/rubrics/{nonce} y las rúbricas de su contained), en los resultados de búsqueda que son rúbricas y en las filas de rúbricas de GET /v0/accessible/cards?type=rubric. Elige rúbricas con can_mark: true; añadir otra responde 403.
• Los oráculos y las agendas marcan solo con rúbricas con las que la propia agenda puede marcar; tu propio derecho no se les presta: Pipeline de API: escribir una agenda para tus oráculos

C. Tu propio árbol de rúbricas

1. Crear.

POST /v0/my/rubrics
Idempotency-Key: rub-1f3a…
{"title": "Wedding services", "content": "What we offer for weddings.", "language": "en",
 "parent": "470000000000000070"}
→ {"nonce": "470000000000000077", "card_type": "rubric", "kind": "tag", "visibility": "Private", …}

• Solo title es obligatorio. parent: una rúbrica en la que puedas escribir y con la que puedas marcar (B3); la nueva queda debajo de ella.
• Una rúbrica nueva está cerrada para marcar: solo tú marcas tarjetas con ella hasta que la abras o la compartas (B3).
• visibility (+ permissions, publicity) se puede fijar al crear; Unlisted y Public necesitan project (uno de los tuyos).
• kind: "place" es para nodos geográficos y necesita geo {lat, lon}, una location y Public para Everyone; rara vez lo necesitarás.
• directed: false e inverse_title describen la rúbrica cuando se usa como etiqueta de una relación: Pipeline de API: unir dos tarjetas con una relación
• exclusive_children: true: la rúbrica acepta un solo hijo a la vez en una tarjeta (árboles de etapas, ver B2).

2. Añadir, quitar y reordenar subrúbricas.

POST   /v0/my/rubrics/{rubric}/{child rubric}   {"seqnum": 3}    → 204   (seqnum optional: default = last)
PATCH  /v0/my/rubrics/{rubric}/{child rubric}   {"seqnum": 0}    → 204   (move)
DELETE /v0/my/rubrics/{rubric}/{child rubric}                    → 204

Ambas deben ser rúbricas en las que puedas escribir, y además necesitas el derecho a marcar con la rúbrica padre (B3); se rechaza un ciclo. Las demás tarjetas no se archivan así: llevan sus rúbricas en su propio campo rubrics (B).

3. Editar, eliminar. PATCH /v0/my/rubrics/{nonce} (title, content, handle, visibility, project, …); DELETE /v0/my/rubrics/{nonce}. Las tuyas: GET /v0/my/rubrics, GET /v0/my/rubrics/{nonce}.

Detrás

• Nada se ejecuta después: las etiquetas y el lugar se guardan con la tarjeta y son lo que comparan los filtros de búsqueda.

Reglas (400)

• at most 20 rubrics per card; rubric <n> listed twice; rubric <n> not found; rubric <n> is not readable; rubric <n> is a place; set it as location; rubric <n> is under another listed rubric (pon solo la más específica); at most 2 primary rubrics per taxonomy root (…).
• Árbol: a rubric cannot be its own parent, would create a cycle, parent must be numeric; una rúbrica en la que no puedes escribir: 404.
• kind must be tag|place; un lugar que aún se usa como location no se puede eliminar ni convertir en etiqueta: <n> cards use this place as their location.
• Marcar (B2): rubric <n> is both in add and remove; rubrics <a> and <b> are both under <parent>, which takes one child at a time: add one; los demás motivos de rúbrica, como en B. Una tarjeta que puedes leer pero no editar: 403; una tarjeta que cambió en ese mismo momento: 409, reintenta.
• Añadir una rúbrica con la que no puedes marcar (en una tarjeta, como location o como padre): 403; ver B3.

Superficie de la API