API-пайплайн: собирать карточки в рабочие пространства

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

Цель: собирать карточки любого типа в рабочие пространства: создать пространство, добавлять, удалять и переупорядочивать карточки, находить, в каких ваших пространствах лежит карточка.

Шаги

1. Создание.

POST /v0/my/workspaces
Idempotency-Key: ws-trip-1
{"title": "Trip ideas", "language": "en"}
→ {"nonce": "470000000000000051", "card_type": "workspace", "visibility": "Private", …}

По желанию: content, handle, visibility + permissions + publicity, rubrics, location, workspaces (положить его внутрь других рабочих пространств, в которые вы можете писать). Без них пространство создаётся Private.

2. Добавьте карточку.

POST /v0/my/workspaces/470000000000000051/470000000000000001
{}
→ 204

Карточка должна быть доступна вам для чтения; она встаёт в конец или на позицию {"seqnum": 0}. Повторное добавление той же карточки ничего не меняет.

3. Порядок: PATCH /v0/my/workspaces/{ws}/{card} {"seqnum": 2} → 204.

4. Удаление из пространства: DELETE /v0/my/workspaces/{ws}/{card} → 204.

5. Чтение.

GET /v0/graph/workspaces/470000000000000051?contained_limit=50&contained_offset=0
→ {"nonce": "…", "i18n": […], "contained": [{tile}, …], "contained_next_offset": 50, …}

Листайте по contained_next_offset, пока он не пропадёт (contained_limit 1–200). GET /v0/my/workspaces/{nonce} возвращает то же для ваших собственных пространств.

6. Поиск пространств: GET /v0/my/workspaces?q=trip&limit=20 (по заголовку); containing=<card nonce>[,<nonce>…] ставит первыми ваши пространства, где уже лежат эти карточки; scope=owned|granted|all.

7. Правка или удаление пространства: PATCH /v0/my/workspaces/{nonce} (title, content, handle, visibility…), DELETE /v0/my/workspaces/{nonce}. Удаление рабочего пространства не удаляет карточки в нём.

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

• Рабочее пространство может содержать карточки любых типов, включая другие рабочие пространства; оно не может содержать само себя или одного из своих предков.
• Доступ: если положить чужую карточку в своё пространство, вы ничем из неё не делитесь; те, с кем вы поделились пространством, получат только карточки, которыми поделились их владельцы. Граф Cabi.Chat — политики карточек
• Карточка в любом из ваших пространств считается сохранённой вами (звёздочка; saved_by_viewer на карточке).

Правила

• 400 a workspace cannot contain itself, would create a cycle, card must be a numeric nonce.
• 404: у вас нет права записи в это пространство, или карточка неизвестна или недоступна вам для чтения.
• 400 для пространства истории: пространства версий заполняет только история версий.

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