API compatibility and updates

1) Compatibility fundamentals

Additive-first: add new without breaking old (new optional fields/endpoints, new enum values).
Stable contracts: "what is promised in the specification works;" behavior documented.
Backward> Forward: backward compatibility priority; forward is allowed through tolerant-readers.
The documents are primary: the only source of truth is the registry version of the scheme (OpenAPI/AsyncAPI/Proto).
Explicit evolution: breaking - only through a new major version and a migration guide.

2) Taxonomy of changes

2. 1 Compatible (MINOR/PATCH)

Add optional fields/headers, new endpoints, query parameters with defaults.
Increasing limits ('page _ size', TTL), clarifying errors without changing codes/semantics.
Add enum values if clients ignore the "unknown" (tolerant-reader).

2. 2 Ambiguous (Behavioral)

Changing defaults, sorting order, thin timeouts, quotas - can "break" business logic. Requires RFC + announcement and canaries.

2. 3 Breaking (MAJOR)

Rename/delete fields, change type/format, replace error codes, reverse incompatibility of contracts/authentication schemes.

3) Versioning policy

Strategy: 'path versioning' ('/v1 ', '/v2').

Minor/patch: "add, don't break."

Dated headers (optional): 'X-API-Version-Date' for soft incremental changes.
Media Types (Op.) : `Accept: application/vnd. acme. v1 + json 'for fine granulation.

4) Deprections and sunset

4. 1 Communication headers

Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </guides/reports-v2>; rel="successor-version"

4. 2 Withdrawal order

1. Announcement in the portal/mailing list/SDK release notes.
2. The warning window ≥ 90-180 days.
3. Statuses in the adoption dashboard.
4. After sunset - 410 Gone or "read-only" mode for grace period, if agreed.

5) Migrations and coexistence of versions

Dual-write/dual-read in transition and reconciliation with reports.
Adapters (temporary): gateway conversions of old payload → new schemes; adapter lifetime is limited.
SDK help: releases that support both versions, with decrement warnings (1 time per process).
Feature flags: inclusion of new semantics according to the list of keys/tenants.

6) Backward and forward compatibility

6. 1 Backward (old clients ↔ new server)

Do not change type formats/mandatory.
New fields are only optional.
Errors - old'error _ code ', add new codes, do not replace.

6. 2 Forward (new clients ↔ old server)

Check for capabilities through'OPTIONS '/'/versions'.
Grace behaviour: The client must be tolerant of missing features.

7) Contracts and automatic checks

Registry: store schema versions; PR digs → breaking/non-breaking reports.
Linter: names/types, idempotency, pagination, stable codes.
CDC (Consumer-Driven Contracts): Integrator tests in the supplier's CI (Pact and analogs).
Gate: PR is blocked when breaking without a'major bump '/RFC.

yaml
- name: API Diff run: api-diff --from main --to $PR_SHA --fail-on=breaking --format junit --out diff. xml

8) Canary extension and reverse

Canary: 10% → 25% → 50% → 100% of traffic; auto-rollback on SLO degradation (5xx/latency/429).
Beta keys: access to new versions by allowlist.
Release freeze: error-budget during combustion.
Acceptance analytics: share of traffic/clients on the new version, migration time.

9) Compatibility in detail: errors, pagination, idempotence

9. 1 Errors

Do not change HTTP statuses in existing scripts.
'error _ code '- stable; new codes only add.
'application/problem + json'is a single format.

9. 2 Pagination

Switch to cursor/keyset = MINOR if the old'offset/limit 'is supported.
Document the sort '(updated_at,id)' and cursor stability.

9. 3 Idempotency

For write - 'Idempotency-Key' + '409 IDEMP_REPLAY' in case of conflict.
Migrations should not change the semantics of idempotency.

10) Gateway transformations (when appropriate)

Map v1→v2 fields, normalize errors, convert date/money formats.
Guardrails: transformations are transparent and logable; do not hide breaking, but use as a time-limited bridge.

11) Communications and Portal

Changelog с датами (`added/changed/deprecated/removed/fixed`).
Version card: status (beta/GA/deprecated), sunset date, links to guides.
Notification webhooks: 'deprecation. notice`, `version. released`, `plan. change`.
SDK release notes + portal banner.

12) Success metrics

Adoption rate v2 (per request/client).
Backward-compat incidents.
Error mix (4xx/5xx/429 shares) before/after release.
Time-to-Adopt median.
Support load (tickets/week).
Cost-to-Serve.

13) Templates and examples

13. 1 Version titles and decrements

X-API-Version: v1
Deprecation: true
Sunset: 2026-03-31T00:00:00Z
Link: </v2/reports>; rel="successor-version"

13. 2 Version policy (YAML fragment)

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 Field Append Compatible

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+" } # additive

14) Release checklist (MINOR/MAJOR)

MINOR

• DIFF: non-breaking, linter green
• Documentation/SDK updated (examples/codecs)
• Canary + auto-SLO rollback
• Comm Plan, Portal Page
• Adoption and error dashboards

MAJOR

• RFC/ADR, sunset date and ≥90 window -180 days
• v1↔v2 bridge and migration guide
• Dual-write/read and reconciliations
• SDK with both APIs + alerts
• Pilot with key integrators

15) Implementation plan (3 iterations)

1. Foundation (2 weeks):

Registry of schemes, lints and auto-diff in CI; compatibility policy; 'Deprecation/Sunset 'titles.

2. Managed releases (3-4 weeks):

Canaries, feature flags, SLO alerts; version portal; SDK releases with support for 2 branches.

3. Automation and scale (continuous):

CDC tests of consumers in CI, sunset forecast on adoption trends, automatic notifications and reminders.

16) Mini-FAQ

Can I change the field type without a major?
No, it isn't. Even "stroka→chislo" is breaking. Enter a new field, the old one is deprecate.

Enum: can you add values?
Yes, if clients are tolerant-readers. Otherwise - first an alert and beta.

How much to hold the old version?
So far, the adoption of the new ≥95% has been maintained. Fix the deadline in the policy.

Total

API compatibility is a discipline: additive approach, formal schemes and diphs, canary releases, clear decrements, and managed migrations. Consolidate change policies, automate checks and communications, measure adoption - and your updates will stop breaking clients, and the speed of evolution will increase without losing reliability.