Skip to main content

Model Artifact: API Evolution and Deprecation Policy

Scenario​

A Semester 7 learner defines how a course project API will evolve without surprising clients.

Completed learner-quality example​

Policy goal​

Allow the API to improve while protecting existing clients from silent breaking changes.

Compatibility rules​

Backward-compatible changes may ship in the current version:

  • Add optional request fields.
  • Add response fields clients are expected to ignore if unknown.
  • Add new endpoints.
  • Widen enum handling on input.

Breaking changes require a new version or a documented deprecation window:

  • Remove or rename fields.
  • Change field meaning, units, or requiredness.
  • Narrow accepted input values.
  • Change authentication behavior.

Deprecation process​

  1. Mark the field or endpoint deprecated in the OpenAPI description.
  2. Add a response header: Deprecation: true.
  3. Publish a migration note with replacement behavior and examples.
  4. Keep the old behavior for at least two minor releases or 90 days, whichever is longer.
  5. Monitor usage; do not remove while active production clients remain above the agreed threshold.

Example: GET /v1/orders/{id}​

total_cents is deprecated in favor of money.total.amount and money.total.currency. Both shapes are returned during the window. New clients must use money; old clients continue to receive total_cents until removal criteria are met.

Review checklist​

  • Does the change alter a client-visible contract?
  • Is there a migration example?
  • Can we detect remaining usage?
  • Is the removal date stated in absolute calendar terms?

How to read this example​

  • Passing: Defines compatible versus breaking changes and a minimum deprecation process.
  • Strong: Includes concrete examples, client communication, and usage monitoring.
  • Portfolio-worthy: Treats API evolution as an operational contract, not just a version string.