Versioning and compatibility

APIs outlive clients. Prefer backward-compatible evolution; version explicitly only when breaking change is unavoidable.

Compatibility tactics:

• **Additive changes**: new optional fields, new endpoints, new enum values clients ignore.
• **Tolerant readers**: clients ignore unknown JSON fields; servers accept omitted new fields with defaults.
• **Deprecation windows**: Sunset header, changelog, metrics on old fields.
• **Version channels**: URL prefix (`/v2/orders`), header (`Accept-Version: 2`), or media type — pick one primary strategy per API surface.

					GET /v2/orders/1
Accept: application/vnd.myapi.orders+json;version=2
				

Breaking examples requiring a new version or new resource:

• Renaming or retyping fields clients depend on.
• Changing error shapes or status code meaning.
• Removing endpoints or narrowing validation.

On interviews: describe how you ship additive changes safely, detect breaking usage, and migrate mobile or third-party consumers.

Common pitfalls: silent breaking changes, multiple versioning schemes at once, versioning every small tweak, and no telemetry on deprecated paths.

The trade-off is URL versioning visibility versus header cleanliness — consistency and documentation matter more than the specific mechanism.

Checklist:

• Default to additive, compatible changes.
• Document deprecation timeline and Sunset.
• One primary versioning scheme per public API.
• CI checks for OpenAPI/schema breaking diffs.