API-пайплайн: рубрики для карточек

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

Цель: отмечать свои карточки рубриками, строить собственное дерево рубрик и просматривать публичные рубрики.

Рубрика — это карточка (card_type: rubric). Вид tag классифицирует карточки; вид place — географический узел (rub.geo-…), он задаётся как location карточки и никогда как тег. Рубрики образуют деревья: рубрика содержит свои подрубрики по порядку.

A. Просмотр публичных рубрик

1. Корни.

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. Дочерние рубрики.

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}

Листайте с contained_offset, пока contained_next_offset не станет null. Найти рубрику по слову: {"query": "dental", "card_type": "rubric", "filters": {"kind": "tag"}} в том же поиске.

3. Карточки в рубрике. Поиск с фильтром по рубрике: "filters": {"rubrics": [["<rubric nonce>"]]} (внутренние списки — ИЛИ, внешний — И; rubrics_not исключает).

B. Отметить карточку

Рубрики — это поле карточки. Отправляйте весь список при создании или PATCH; он заменяет предыдущий. Для каждой рубрики, которую добавляет новый список, нужно право отмечать ею (B3); рубрики, которые уже есть на карточке, остаются.

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

• Карточки, принимающие рубрики: project, article, post, board, doc, sheet, workspace, coupon, room.
• primary_rubrics (по желанию): те, что показываются первыми; не больше 2 на дерево. Без этого поля основными считаются первые рубрики каждого дерева.
• location: одна рубрика-место; "" очищает поле. Найдите её через GET /v0/search/geo/cities?q=…, затем GET /v0/graph/resolve/@rub.geo-<geonameid>.
• rubrics: [] снимает все теги.

B2. Отметить карточку: добавить и снять за один вызов

Меняйте часть рубрик карточки, не отправляя весь список заново.

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"}]}

• Работает на любой карточке, принимающей рубрики, если вы можете её редактировать. Рубрики, которых нет в запросе, остаются как есть.
• В ответе видны только рубрики, которые вы можете читать.

Деревья этапов. Поставьте exclusive_children: true на свою рубрику (при создании или через PATCH), и на карточке она будет принимать только одну дочернюю за раз: добавление дочерней заменяет соседнюю, которая была на карточке. Так удобно вести этапы, например Новый → Связались → Сделка: один вызов на шаг, перескоки разрешены. transitions перечисляет каждый шаг по дереву (from: null — карточка вошла в дерево, to: null — вышла из него).

История. Каждая отметка записывается как изменение: что добавлено и что снято, переходы между этапами, кто и когда.

B3. Кто может отмечать рубрикой

Чтобы добавить рубрику на карточку, нужно право отмечать этой рубрикой. Чтобы снять рубрику, оно не нужно никогда.

• Свои рубрики: ими вы можете отмечать всегда.
• Чужая рубрика: отмечать ею можно, если она открыта для отметок (её собственное право выполнения — для всех, кто может её читать), или если владелец поделился ею с вами с правом выполнения — грантом или ссылкой доступа, выданными на саму эту рубрику. Доступ к родительской рубрике или к воркспейсу выше не считается: каждая рубрика решает за себя. Общие публичные таксономии открыты для отметок.
• Новые рубрики создаются закрытыми (выполнение выключено): отмечать ими можете только вы. Открыть рубрику всем, кто может её читать: PATCH /v0/my/rubrics/{nonce} {"permissions": {"read": true, "write": false, "execute": true}} (рубрика Unlisted или Public; Private остаётся только вашей). Открыть её выбранным людям или агендам — поделиться с правом выполнения: API-пайплайн: делиться карточками через ссылки доступа
• Проверяется только то, что изменение добавляет. Рубрики, которые уже есть на карточке, остаются при повторном сохранении. То же право нужно для новой location и для родительской рубрики, когда вы ставите под неё рубрику.
• can_mark (true / false, только для вошедших) подсказывает заранее: на странице рубрики (GET /v0/graph/rubrics/{nonce} и рубрики в её contained), в найденных поиском рубриках и в строках рубрик GET /v0/accessible/cards?type=rubric. Выбирайте рубрики с can_mark: true; добавление другой отвечает 403.
• Оракулы и агенды отмечают только рубриками, которыми может отмечать сама агенда; ваше право им не передаётся: API-пайплайн: написать агенду для своих оракулов

C. Ваше собственное дерево рубрик

1. Создание.

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

• Обязателен только title. parent: рубрика, в которую вы можете писать и которой можете отмечать (B3); новая рубрика встаёт под неё.
• Новая рубрика закрыта для отметок: отмечать ею карточки можете только вы, пока не откроете её или не поделитесь ею (B3).
• visibility (+ permissions, publicity) можно задать при создании; Unlisted и Public требуют project (один из ваших).
• kind: "place" — для географических узлов, требует geo {lat, lon}, location и Public для Everyone; это нужно редко.
• directed: false и inverse_title описывают рубрику, когда она используется как метка связи: API-пайплайн: связать две карточки отношением
• exclusive_children: true: рубрика принимает на карточке только одну дочернюю за раз (деревья этапов, см. B2).

2. Добавление, удаление, порядок подрубрик.

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

Обе должны быть рубриками, в которые вы можете писать, и нужно право отмечать родительской рубрикой (B3); цикл отклоняется. Другие карточки так не раскладываются: они несут рубрики в собственном поле rubrics (B).

3. Правка, удаление. PATCH /v0/my/rubrics/{nonce} (title, content, handle, visibility, project, …); DELETE /v0/my/rubrics/{nonce}. Ваши: GET /v0/my/rubrics, GET /v0/my/rubrics/{nonce}.

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

• Ничего не выполняется позже: теги и место сохраняются вместе с карточкой и именно по ним работают фильтры поиска.

Правила (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 (указывайте только самую точную); at most 2 primary rubrics per taxonomy root (…).
• Дерево: a rubric cannot be its own parent, would create a cycle, parent must be numeric; рубрика, в которую вы не можете писать: 404.
• kind must be tag|place; место, которое ещё используется как location, нельзя удалить или превратить в тег: <n> cards use this place as their location.
• Отметка (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; остальные причины по рубрикам — как в B. Карточка, которую вы можете читать, но не редактировать: 403; карточка изменилась в тот же момент: 409, повторите.
• Добавление рубрики, которой вы не можете отмечать (на карточку, как location или как родительскую): 403; см. B3.

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