Cabi.Chat API — Создание карточек: идемпотентность и лимиты

Создание карточки через Cabi.Chat API — это один POST /v0/my/<type>. Две вещи делают его безопасным для повторов и честным для всех: ключ идемпотентности на каждом создании и лимит запросов на каждого вызывающего. Создание, повторённое с тем же ключом, возвращает первый результат и никогда не делает копию.

Idempotency-Key

Сеть может оборваться на полпути. Без ключа повтор после таймаута может создать одну и ту же карточку дважды. С ключом — не может.

• Каждое создание отправляет Idempotency-Key: <any unique string>, до 255 символов; обычно это UUID. Это каждый POST /v0/my/<type>, а также контакты и связи проекта. Создание без ключа отвечает 400.
• Делайте один ключ на попытку создания и используйте его в каждом повторе этой попытки.
• Тот же ключ, то же тело, первый вызов завершён: вы снова получаете первый ответ, байт в байт, с заголовком idempotent-replayed: true. Второй карточки не будет.
• Тот же ключ, то же тело, первый вызов ещё выполняется: 409. Подождите и повторите.
• Тот же ключ, другое тело: 400. Ключ принадлежит одному телу.
• Неудачное создание (любой ответ не 2xx) освобождает ключ, так что повтор может использовать его снова.
• Персональные токены доступа и токены оракулов показываются один раз: повтор такого создания с тем же ключом отвечает 409 и никогда не отдаёт токен снова. Cabi.Chat API — Персональные токены доступа

Лимит запросов

Создания ограничены для каждого вызывающего, по всем типам карточек вместе. Сверх лимита ответ — 429: подождите несколько секунд и повторите с тем же ключом.

Политики при создании

• Чтобы открыть новую карточку, отправьте visibility вместе с publicity и permissions в одном PATCH. С какими настройками карточка создаётся и какие может иметь: Граф Cabi.Chat — политики карточек
• Карточка, кроме проекта, привязывается к своему проекту через project — при создании или в patch. Cabi.Chat Graph — Типы данных
• workspaces: [<nonce>] при создании сразу кладёт карточку в ваши скрепки.

Хендлы и текст

• Хендлы и упоминания: Cabi.Chat Graph — Хендлы, упоминания и связи
• Текст — CommonMark. Посты — Telegram MarkdownV2.
• Две одновременные правки одной статьи: более поздняя отклоняется с card changed concurrently — retry. Прочитайте статью заново и повторите.

Создание проекта с местом, сферой и контактами, шаг за шагом: API-пайплайн: создание и редактирование страницы проекта

Все эндпоинты: Cabi.Chat API — эндпоинты графа