Сумісність API та оновлення
1) Базові принципи сумісності
Additive-first: додавайте нове, не ламаючи старе (нові опціональні поля/ендпоінти, нові enum-значення).
Стабільні контракти: «що обіцяно в специфікації - те й працює»; поведінка документована.
Backward > Forward: пріоритет зворотної сумісності; forward допускається через tolerant-readers.
Документи первинні: єдине джерело правди - версія схеми в registry (OpenAPI/AsyncAPI/Proto).
Явна еволюція: breaking - тільки через нову major-версію і міграційний гід.
2) Таксономія змін
2. 1 Сумісні (MINOR/PATCH)
Додавання опціональних полів/хедерів, нових ендпоінтів, query-параметрів з дефолтами.
Збільшення лімітів ('page _ size', TTL), уточнення помилок без зміни кодів/семантики.
Додавання значень enum, якщо клієнти ігнорують «незнайомі» (tolerant-reader).
2. 2 Неоднозначні (Behavioral)
Зміна дефолтів, порядку сортування, тонких таймаутів, квот - може «ламати» бізнес-логіку. Вимагає RFC + анонс і канарок.
2. 3 Ламаючі (MAJOR)
Перейменування/видалення полів, зміна типу/формату, заміна кодів помилок, зворотна несумісність контрактів/схем аутентифікації.
3) Політика версіонування
Стратегія: `path versioning` (`/v1`, `/v2`).
Мінор/патч: «додай, не ламай».
Датовані заголовки (доп.): 'X-API-Version-Date'для м'яких поступових змін.
Медіа-типи (опц.) : `Accept: application/vnd. acme. v1 + json'для тонкої грануляції.
4) Депрекації і sunset
4. 1 Комунікаційні заголовки
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"4. 2 Порядок виведення
1. Анонс в порталі/розсилці/SDK release notes.
2. Вікно попередження ≥ 90-180 днів.
3. Статуси в дашборді adoption.
4. Після sunset - 410 Gone або «read-only» режим на період grace, якщо погоджено.
5) Міграції та спільне співіснування версій
Dual-write/dual-read в перехідний період і звірка звітами.
Адаптери (тимчасові): gateway-перетворення старих payload → нові схеми; термін життя адаптера обмежений.
SDK-допомога: релізи, що підтримують обидві версії, з попередженнями депрекації (1 раз за процес).
Фіча-прапори: включення нової семантики за списком ключів/тенантів.
6) Backward і forward сумісність
6. 1 Backward (старі клієнти ↔ новий сервер)
Не змінювати формати типів/обов'язковість.
Нові поля - тільки опціональні.
Помилки - колишні'error _ code', нові коди додавати, не замінювати.
6. 2 Forward (нові клієнти ↔ старий сервер)
Перевіряти наявність можливостей (capabilities) через'OPTIONS '/'/versions'.
Грейс-поведінка: клієнт повинен терпимо ставитися до відсутніх фічів.
7) Контракти та автоматичні перевірки
Registry: зберігаємо версії схем; PR-дифи → звіти «breaking/non-breaking».
Лінтер: імена/типи, ідемпотентність, пагінація, стабільні коди.
CDC (Consumer-Driven Contracts): тести інтеграторів в CI постачальника (Pact і аналоги).
Гейт: PR блокується при breaking без'major bump '/RFC.
yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml8) Канарний випуск і зворотний хід
Canary: 10% → 25% → 50% → 100% трафіку; авто-відкат при погіршенні SLO (5xx/latency/429).
Бета-ключі: доступ новим версіям по allowlist.
Release freeze: при згорянні error-budget.
Аналітика прийняття: частка трафіку/клієнтів на новій версії, час міграції.
9) Сумісність в деталях: помилки, пагінація, ідемпотентність
9. 1 Помилки
Не змінювати HTTP-статуси в існуючих сценаріях.
'error _ code'- стабільний; нові коди тільки додавати.
'application/problem + json'- єдиний формат.
9. 2 Пагінація
Перехід на cursor/keyset = MINOR, якщо підтриманий старий'offset/limit'.
Документуйте сортування'( updated_at,id)'і стабільність курсору.
9. 3 Idempotency
Для write -'Idempotency-Key'+'409 IDEMP_REPLAY' при конфлікті.
Міграції не повинні змінювати семантику ідемпотентності.
10) Gateway-трансформації (коли доречно)
Map v1→v2 полів, нормалізувати помилки, конвертувати формати дат/грошей.
Guardrails: трансформації прозорі і логуються; не ховайте breaking, а використовуйте як міст з обмеженим терміном.
11) Комунікації та портал
Changelog с датами (`added/changed/deprecated/removed/fixed`).
Картка версії: статус (beta/GA/deprecated), дата sunset, посилання на гайди.
Вебхуки повідомлень: `deprecation. notice`, `version. released`, `plan. change`.
SDK release notes + банер в порталі.
12) Метрики успіху
Adoption rate v2 (за запитами/клієнтам).
Backward-compat incidents (кількість «ломок»).
Error mix (частки 4xx/5xx/429) до/після релізу.
Time-to-Adopt медіана.
Support load (тікети/нед).
Cost-to-Serve (інфраструктурна вартість на виклик).
13) Шаблони та приклади
13. 1 Заголовки версій і депрекацій
X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"13. 2 Політика версій (фрагмент YAML)
yaml versioning:
strategy: "path"
compatibility:
minor: "additive-only"
patch: "bugfix/perf, no schema change"
deprecation:
min_notice_days: 120 rollout:
canary_steps: [10,25,50,100]
rollback_checks: ["5xx_rate","p95_latency","429_rate","adoption"]13. 3 OpenAPI: сумісне додавання поля
yaml components:
schemas:
Report:
type: object required: [id, createdAt]
properties:
id: { type: string }
createdAt: { type: string, format: date-time }
cursor: { type: string, description: "optional for v1. 2+" } # additive14) Чек-лист релізу (MINOR/MAJOR)
MINOR
- DIFF: non-breaking, лінтер зелений
- Документація/SDK оновлені (приклади/кодеки)
- Канарка + авто-відкат по SLO
- Комм-план, сторінка в порталі
- Дашборди adoption і помилок
MAJOR
- RFC/ADR, дата sunset і вікно ≥90 -180 днів
- v1↔v2 міст (gateway) і міграційний гід
- Dual-write/read і звірки
- SDK з обома API + попередження
- Пілот з ключовими інтеграторами
15) План впровадження (3 ітерації)
1. Фундамент (2 тижні):
Registry схем, лінт і auto-diff в CI; політика сумісності; заголовки «Deprecation/Sunset».
2. Керовані релізи (3-4 тижні):
Канарки, фіча-прапори, SLO-алерти; портал версій; SDK-релізи з підтримкою 2 гілок.
3. Автоматизація та масштаб (безперервно):
CDC-тести споживачів в CI, прогноз sunset по трендах adoption, автоматичні нотифікації і нагадування.
16) Міні-FAQ
Чи можна змінювати тип поля без major?
Ні, ні. Навіть «stroka→chislo» - breaking. Введіть нове поле, старе - deprecate.
Enum: чи можна додавати значення?
Так, якщо клієнти - tolerant-readers. Інакше - спочатку оповіщення і бета.
Скільки тримати стару версію?
Поки adoption нової ≥95% і витримано вікно депрекації. Фіксуйте термін у політиці.
Підсумок
Сумісність API - це дисципліна: additive-підхід, формальні схеми і дифи, канарські релізи, ясні депрекації і керовані міграції. Закріпіть політику змін, автоматизуйте перевірки та комунікації, міряйте adoption - і ваші оновлення перестануть ламати клієнтів, а швидкість еволюції зросте без втрати надійності.