API Versioning

The Permanence Problem

 the moment a second consumer exists, your API is a PROMISE:

 - mobile apps in app-store review limbo (weeks old versions!)
 - partner integrations nobody can redeploy quickly
 - internal services on different upgrade cadences

 breaking changes don't break TESTS — they break DEPLOYED
 CLIENTS YOU CANNOT TOUCH. versioning strategy = how you
 keep evolving while promises hold.

The Versioning Placements

 URI PATH:      /v2/orders          ← most visible, easiest routing
 HEADER:        Accept: application/vnd.acme+json; v=2
                ← cleaner URIs; invisible/harder to debug
 HOST/PACKAGE:  api-v2.example.com / separate SDK majors
 QUERY PARAM:   ?version=2          ← weakest; caching quirks

 practical verdicts:
 - public/multi-client APIs: URI versioning wins on clarity
   and CDN/LB routability. boring is correct here.
 - fine-grained media evolution: header/content-negotiation
 - ALL of them beat "no versioning, break carefully"

What Counts as Breaking

 SAFE (additive) ✓                    BREAKING ✗
 new optional field                   removing/renaming fields
 new endpoint                         changing field types/semantics
 widening enums w/ unknown-handling   narrowing/removing enum values
 relaxing validation                  tightening validation
 new query params (optional)          changing auth/error shapes

 the sneaky ones:
 ⚠ semantic drift: field stays, MEANING changes ("total" now
   includes tax) — breaks consumers with zero schema diff!
 ⚠ pagination defaults, sort orders, error-code remapping

 rule of thumb: if a reasonable client could observe a
 difference it didn't opt into — it's breaking.

Lifecycle Management

 version DEPRECATION is half the discipline:

 □ overlap window: old + new live simultaneously;
   migration is the CONSUMER'S choice pace (bounded by your sunset)
 □ sunset POLICY published: e.g., N-1 supported 12 months;
   partners contractually notified
 □ TELEMETRY per version per client: who still calls v1?
   deprecation dates set from DATA, not hope
 □ RESPONSE WARNINGS: Deprecation/Sunset headers on old versions —
   clients discover deadlines programmatically  
 □ CONTRACT TESTS both directions: producer against all
   live versions; consumers pinned to what they read

Strategy	Best fit
Additive-only forever	internal services you control
Major-versioned URIs	public APIs, mobile clients
Date-based versions	slow-moving partner platforms
GraphQL schema evolution	flexible clients (fields nullable-first)

 event/message schemas follow the same rules with a
 twist: HISTORY replays forever → backward compatibility
 is non-negotiable there (schema-evolution lesson).

Interview Framing

“Your orders API needs a breaking change but mobile ships biweekly” scored answer: additive-first attempt explored honestly, major version created WITH overlap window sized to app-store reality, telemetry-driven sunset policy, semantic-drift warning included, contract tests named. API-evolution questions test whether you design for clients you’ll never meet — empathy encoded as engineering.