How do you version microservice APIs without breaking consumers?

Expected Interview Answer

Step-by-Step Explanation

1. Step 1

   Prefer additive changes

   Add optional fields and new endpoints instead of removing, renaming, or retyping existing ones to stay backward compatible.

2. Step 2

   Design tolerant readers

   Have clients ignore unknown fields so producers can extend responses without breaking consumers.

3. Step 3

   Choose a versioning scheme

   For breaking changes, expose an explicit version via URL path, header, or media type and follow semantic versioning.

4. Step 4

   Run versions in parallel

   Serve v1 and v2 simultaneously so consumers migrate on their own schedule rather than all at once.

5. Step 5

   Guard with contract tests

   Use consumer-driven contract tests (e.g., Pact) in CI to catch breaking changes before they ship.

6. Step 6

   Deprecate deliberately

   Announce timelines, monitor per-version usage, and retire the old version only after consumers have moved.

Code Example

GET /v1/orders/123 HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK
Deprecation: true
Sunset: Wed, 31 Dec 2026 23:59:59 GMT
Link: </v2/orders/123>; rel="successor-version"

{
  "id": 123,
  "total": 49.90
}

--- migrated consumer ---
GET /v2/orders/123 HTTP/1.1
Host: api.example.com
Accept: application/json

HTTP/1.1 200 OK

{
  "id": 123,
  "total": { "amount": 49.90, "currency": "USD" }
}

Follow-up Questions

• URL path versioning vs header versioning: which do you prefer and why?
• What counts as a breaking change in a REST API?
• How do consumer-driven contract tests prevent breakage?
• How do you communicate and enforce a deprecation timeline?
• How does GraphQL handle evolution differently from REST versioning?