Соглашения

Регистр полей

Все поля запросов и ответов используют snake_case — например, due_date, task_status_id.

Обёртки ответа

Успешные ответы оборачиваются в обёртку data:

{ "data": { "id": "task_6a2918cff58b0a1d387866ee" } }

Списочные эндпоинты добавляют объект pagination:

{
  "data": [ /* … */ ],
  "pagination": { "next_cursor": "…", "has_more": true }
}

Ошибки используют отдельную обёртку — см. Ошибки.

Пагинация

Списочные эндпоинты используют пагинацию по курсору. Передайте next_cursor из предыдущего ответа, чтобы получить следующую страницу; has_more подсказывает, когда остановиться. Считайте курсор непрозрачным.

Идемпотентность

POST-запросы (создание) принимают заголовок Idempotency-Key. Отправьте уникальный ключ (до 255 символов — хорошо подойдёт UUID), чтобы повторённый запрос не смог создать дубликат:

curl -X POST https://api.bordio.com/public/v1/tasks \
  -H "Authorization: Bearer brd_sk_live_..." \
  -H "Idempotency-Key: 6a2918cf-f58b-0a1d-3878-66ee00000001" \
  -H "Content-Type: application/json" \
  -d '{ "title": "New task" }'

Как это работает:

• Тот же ключ, то же тело → возвращается сохранённый результат; ничего нового не создаётся.
• Тот же ключ, другое тело → 409 conflict_error (already_exists).
• Тот же ключ, пока первый запрос ещё в процессе выполнения → 409 conflict_error — повторите после завершения первого.
• Ключи запоминаются на 24 часа, затем истекают — повторное использование ключа после этого считается совершенно новым запросом.
• Ключ привязан к своему эндпоинту (и рабочему пространству): тот же ключ на другом эндпоинте независим.
• Только POST идемпотентен через этот заголовок. PATCH/DELETE — нет: PATCH безопасно повторять по своей природе, поскольку он устанавливает поля в значения, которые вы отправляете.