Рабочий код и практика по теме — разборы, инструкции и кейсы для интеграции BOTIX.
Чтение из API — три задачи: листать коллекции, ловить события, разбирать инциденты. Под каждую свой паттерн: cursor, webhook вместо polling, журнал в кабинете.
«Сначала запустим, потом доработаем мелочи» в публичном API = breaking change на каждом релизе. Почему формат ошибки, cursor и rate-limit — это контракт.
Чек-лист, отделяющий рабочий POST от готового к интеграторам: Idempotency-Key с TTL и коллизиями, серверный retry 1m/15m/1h/24h, заголовки X-RateLimit.
Три механизма для трёх классов проблем: Idempotency-Key от дублей POST, HMAC от phishing webhook, timestamp + event.id от replay. Разбор с кодом Verifier.
Кейс BOTIX: три жалобы после v1.0 — дубли POST, потеря записей на offset, пропавший webhook. Как добавили Idempotency-Key, cursor и retry с dead-letter.
Idempotency-Key на POST, разбор error response, cursor вместо offset, таймауты и retry только на нужные коды. Пять правил с кодом на Python.
Публичный API — это контракт: что такое breaking change и зачем 12 месяцев deprecation, как делать backoff по X-RateLimit-* и что нужно API для white-label.
Как перевезти интеграторов с v1.0 на v1.1 без обрыва: критерий breaking change, X-API-Deprecation в каждом ответе, cursor вместо offset и audit-лог отстающих.
Что считать breaking change, cursor вместо offset и три SDK из openapi.yaml. Разбор решений при открытии публичного API BOTIX v1.1.0.
