Pipeline de API: dibujar tableros, llevar documentos y hojas
Índice: Pipelines de API — índice
Objetivo: dibujar un tablero (un lienzo libre o tarjetas dispuestas en un lienzo) y llevar tarjetas de documento y de hoja cuyo contenido guardas tú.
Los tableros, documentos y hojas son tarjetas con un título, un texto y una escena: el contenido como una sola cadena, guardado con un número de revisión. Los documentos y las hojas usan las mismas llamadas que los tableros; las rutas de abajo dicen boards, usa docs o sheets para ellos.
Pasos
1. Crear.
POST /v0/my/boards
Idempotency-Key: board-2b7c…
{"title": "Shop floor plan", "kind": "flow", "content": "Where each service sits.",
"language": "en", "project": "470000000000000001"}
→ {"nonce": "470000000000000060", "card_type": "board", "kind": "flow", "visibility": "Private", "scene_rev": 0, …}
- Solo
titlees obligatorio. Los tableros aceptankind:excalidraw(por defecto, dibujo libre) oflow(tarjetas en un lienzo). Los documentos y las hojas no tienen kind. - Los mismos campos opcionales que un artículo:
content,language,handle,project,workspaces,rubrics,location,translate_mode,translate_langs. Pipeline de API: escribir artículos y publicaciones
2. Guardar la escena.
PUT /v0/my/boards/470000000000000060/scene
{"scene": "{\"nodes\":[{\"id\":\"n1\",\"type\":\"card\",\"position\":{\"x\":0,\"y\":0},\"data\":{\"card_type\":\"project\",\"nonce\":\"470000000000000001\"}}],\"edges\":[]}",
"revision": 0}
→ {"scene_rev": 1}
revisiondebe ser igual alscene_revactual (de la última lectura o guardado); la respuesta trae el nuevo. Una revisión desfasada: 400stale revision: submitted 0, current 1— lee la tarjeta, combina los cambios y reintenta.excalidraw: la escena es un JSON de escena de Excalidraw.flow:{"nodes": […], "edges": […]}; un nodo{"type": "card", "data": {"card_type": "…", "nonce": "…"}}coloca una tarjeta en el lienzo.- Documentos y hojas: la escena es cualquier cadena que elijas (tu propio formato).
- Cualquiera con escritura sobre la tarjeta puede guardar la escena.
3. Leer. GET /v0/my/boards/{nonce|@handle} → la tarjeta con scene y scene_rev. Públicos: GET /v0/graph/boards, GET /v0/graph/boards/{nonce} (también /v0/graph/docs, /v0/graph/sheets). Los tuyos: GET /v0/my/boards (scope, archived como en los artículos).
4. Editar, compartir, eliminar. PATCH /v0/my/boards/{nonce} (title, content, visibility, project, rubrics, …; mismas reglas que los artículos); archivar con POST /v0/my/archive; DELETE /v0/my/boards/{nonce}.
Detrás
- Los nodos de tarjeta de un tablero flow cuentan como menciones: tras guardar, esas tarjetas vuelven en
mentioneddel tablero.
Reglas (400)
title is required;kind must be excalidraw|flow, got ….stale revision: submitted <n>, current <m>.- Reglas de visibilidad, proyecto y rúbricas como en los artículos. Una tarjeta en la que no puedes escribir: 404.
Superficie de la API
| Endpoint | Para qué | FE | IA / oráculo |
|---|---|---|---|
POST /v0/my/boards |
Crear un tablero | sí | sí |
PUT /v0/my/boards/{nonce}/scene |
Guardar el lienzo | sí (guardado automático) | sí |
PATCH/DELETE /v0/my/boards/{nonce} |
Editar, eliminar | sí | sí |
GET /v0/my/boards, GET /v0/graph/boards (+ /{nonce}) |
Los tuyos, públicos | sí | sí |
POST /v0/my/docs, POST /v0/my/sheets (+ /{nonce}, /{nonce}/scene) |
Documentos y hojas | solo API | sí |
GET /v0/graph/docs, GET /v0/graph/sheets (+ /{nonce}) |
Documentos y hojas públicos | solo búsqueda | sí |