API-пайплайн: доски, документы и таблицы

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

Цель: нарисовать доску (свободный холст или карточки, разложенные на холсте) и вести карточки документов и таблиц, содержимое которых вы храните сами.

Доски, документы и таблицы — это карточки с заголовком, текстом и сценой: содержимым в виде одной строки, которое сохраняется с номером ревизии. Документы и таблицы используют те же вызовы, что и доски; в путях ниже указано boards, для них используйте docs или sheets.

Шаги

1. Создание.

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

• Обязателен только title. Доски принимают kind: excalidraw (по умолчанию, свободное рисование) или flow (карточки на холсте). У документов и таблиц нет kind.
• Те же необязательные поля, что и у статьи: content, language, handle, project, workspaces, rubrics, location, translate_mode, translate_langs. API-пайплайн: статьи и посты

2. Сохраните сцену.

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}

• revision должен совпадать с текущим scene_rev (из последнего чтения или сохранения); в ответе — новый. Устаревшая ревизия: 400 stale revision: submitted 0, current 1 — прочитайте карточку, объедините изменения, повторите.
• excalidraw: сцена — это JSON сцены Excalidraw. flow: {"nodes": […], "edges": […]}; узел {"type": "card", "data": {"card_type": "…", "nonce": "…"}} помещает карточку на холст.
• Документы и таблицы: сцена — любая строка на ваш выбор (ваш собственный формат).
• Сохранять сцену может любой, у кого есть право записи на карточку.

3. Чтение. GET /v0/my/boards/{nonce|@handle} → карточка со scene и scene_rev. Публичные: GET /v0/graph/boards, GET /v0/graph/boards/{nonce} (а также /v0/graph/docs, /v0/graph/sheets). Ваши: GET /v0/my/boards (scope, archived — как для статей).

4. Правка, доступ, удаление. PATCH /v0/my/boards/{nonce} (title, content, visibility, project, rubrics, …; те же правила, что для статей); архивация через POST /v0/my/archive; DELETE /v0/my/boards/{nonce}.

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

• Узлы-карточки на доске flow считаются упоминаниями: после сохранения эти карточки возвращаются в mentioned доски.

Правила (400)

• title is required; kind must be excalidraw|flow, got ….
• stale revision: submitted <n>, current <m>.
• Правила видимости, проекта и рубрик — как для статей. Карточка, в которую вы не можете писать: 404.

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