Sign in Get started

API Platform & Lifecycle · Capstone

Capstone: Ship a Necessary Breaking Change

Plan the migration of a widely used endpoint to a new model.

Scenario

Your GET /v1/shipments/{id} returns "weight": 12.5 (kg as float) and "eta": "2026-10-10 14:00" (local time, no zone). Partners misinterpret both, causing billing disputes. You must move to "weight": {"value": 12500, "unit": "g"} and RFC 3339 UTC timestamps. 400 partners use the endpoint; some integrations are unmaintained.

Requirements

  • Fix the data model
  • Minimize partner disruption
  • Know when it's safe to remove the old format

Constraints

  • Contracts promise 12 months' notice for breaking changes

Deliverables

  1. Choose a migration mechanism and timeline.
  2. How do you track and support migration?

Draft each deliverable below before revealing the model answer and rubric.

Further reading: RFC 8594: The Sunset HTTP Header Field

Deliverables

Choose a migration mechanism and timeline.

Model answer

Option A (additive): add weight_v2 / eta_utc fields now, deprecate old fields with Deprecation/Sunset headers, remove after 12 months. Option B (versioned): ship /v2/shipments (or date-pinned version) with the new model; /v1 unchanged until sunset. Prefer A for a single field change (no parallel stack); B if the whole resource is changing. Timeline: announce T0 → SDK release T0 → usage tracking → reminders at 6/9/11 months → brownouts in the final month → remove at T0+12 months, return 410/clear errors afterward.

Rubric

Look for contract-respecting timelines, usage tracking and brownouts. Misses: in-place breaking change, no plan for unmaintained integrations.

How do you track and support migration?

Model answer

Instrument field-level usage (log which consumers read old fields via response analytics or SDK telemetry, or which call /v1); dashboard per partner; targeted emails and account-manager outreach for top users; migration guide with before/after examples and a test endpoint; SDK releases emitting deprecation warnings.

Rubric

Strong answers make migration measurable per consumer and provide tooling, not just announcements.

Open in the app to mark lessons complete, take notes and track your progress.