Evolution and Compatibility Lab

Retrieval Prompts

1. State from memory the eight-item breaking-change checklist.
2. Give three examples of safe changes to a JSON response and three examples of breaking changes.
3. Name three versioning strategies and one real API that uses each.
4. State the two HTTP headers used to signal deprecation and sunset, and give an example value for each.
5. Why is 410 Gone preferred over 404 Not Found for a removed endpoint?

Compare and Distinguish

Separate these pairs cleanly:

• backward compatibility vs forward compatibility - which does each protect?
• URL-path version bump vs adding a new endpoint - when is each appropriate?
• soft-deleting a field (marked deprecated, still present) vs removing it
• announcement via changelog vs announcement via Deprecation header - why you need both
• "ignore unknown fields" tolerance vs "strict schema" parsing - how each reacts to additive changes

Common Mistake Check

Identify the error in each:

1. "Adding a field is always safe." (What configuration of client parser makes this false?)
2. "We're changing amount from dollars to cents in v1.2 because it's just a unit change."
3. "The endpoint is now deprecated. We removed it from the docs. That should be enough."
4. "Our sunset was last week; we kept it running anyway because a customer asked."
5. "We're moving the currency inside a nested money object. Old clients will just ignore the extra nesting."

Spec-Diff Drill

Given v1 and proposed v2 of the Order response:

v1:

{
  "id": "ord_1",
  "customer_id": "c_9",
  "total": 4599,
  "currency": "USD",
  "status": "paid",
  "items": [
    { "sku": "s_1", "quantity": 2, "unit_price": 2299 }
  ],
  "created_at": "2026-04-10T15:19:58Z"
}

Proposed v2:

{
  "id": "ord_1",
  "customer": { "id": "c_9", "email": "a@example.com" },
  "total": { "amount_minor": 4599, "currency": "USD" },
  "status": "PAID",
  "state": "COMPLETED",
  "items": [
    { "sku": "s_1", "quantity": 2,
      "unit_price": { "amount_minor": 2299, "currency": "USD" } }
  ],
  "created_at": "2026-04-10T15:19:58Z",
  "paid_at": "2026-04-10T15:20:02Z"
}

For each change:

1. Classify as safe / breaking.
2. If breaking, propose how to deliver the value without breaking v1 (new parallel field, new endpoint, opt-in header, etc.).
3. Write the deprecation plan for v1 after v2 is released: announce date, sunset date, headers, migration guide table of contents.

Expect 8-10 distinct changes.

Versioning Design

Pick a versioning strategy for the API in the diff above. Write:

1. The choice (URL, header, both) and a three-sentence justification.
2. The URL pattern and the header contract.
3. The rule for what a version bump means in this API.
4. The supported-versions paragraph for the docs.
5. The behavior when a request omits the version (default to latest? reject? error?).

Deprecation Playbook

Write a reusable deprecation playbook (template, not example-specific):

1. Runway lengths by audience.
2. The four stages with dates relative to sunset.
3. Headers emitted at each stage.
4. The outreach channels and when each is used.
5. The metrics that tell you the deprecation is ready to remove.
6. The escalation path if a large consumer has not migrated.
7. The acceptable reasons to slip the sunset date.

This is a reusable artifact - aim for one page.

Evidence Check

This page is complete only if, given any proposed API change, you can:

• classify it as safe, breaking, or both in under one minute
• if breaking, propose a compatible path that delivers the value
• write the deprecation plan with real dates, real headers, and real removal behavior
• defend the versioning strategy against at least one challenger