API Versioning & Lifecycle

Encoding the API version directly in the URL path: /api/v1/users. Simple, visible, and cache-friendly.

"URI versioning lets us run /api/v1 and /api/v2 simultaneously so existing clients are unaffected while new clients adopt the latest version."

Specifying the API version via a request header such as Accept: application/vnd.myapi+json;version=2; keeps URLs clean but less discoverable.

"GitHub's API uses Accept: application/vnd.github.v3+json for header versioning — the URL stays clean but clients must set the header correctly."

Mechanism where client and server agree on the response format and version via Accept and Content-Type headers.

"Content negotiation lets a single endpoint serve JSON, XML, or a versioned JSON variant depending on the client's Accept header."

SemVer; MAJOR.MINOR.PATCH format: a breaking change increments MAJOR, a backwards-compatible feature increments MINOR, and a bug fix increments PATCH.

"Bumping to v3.0.0 signals a breaking change — consumers know they must read the migration guide; v2.5.0 is a safe upgrade for all v2 clients."

An API modification that requires existing consumers to update their code: removing a required field, renaming an endpoint, or changing a data type.

"Renaming the userId field to id in the response was a breaking change — all clients using the old field name began failing until they updated."

An additive change that does not break existing consumers: adding a new optional field, a new endpoint, or a new enum value in a lenient parser.

"Adding an optional metadata object to the response is a non-breaking change — existing clients ignore the unknown field and continue working."

Declaring that an API feature will be removed in a future version; communicated via documentation, changelog, Deprecation header, and migration guide.

"We deprecated the /v1/users endpoint 12 months before removal, including a Deprecation header in every response pointing to the migration guide."

HTTP response header that signals when an endpoint will be removed: Sunset: Sat, 01 Jan 2027 00:00:00 GMT. Defined in RFC 8594.

"Our gateway injects a Sunset header into every v1 response — monitoring tooling alerts API consumers whose traffic is still hitting deprecated endpoints."

The stages an API passes through: design, build, test, publish, version, deprecate, and retire.

"We follow a formal API lifecycle: design reviews gate the build phase, and no endpoint is retired without a six-month deprecation notice."

A new API version works correctly with clients written for the previous version; new fields are optional and existing fields retain their type and semantics.

"We maintain backward compatibility by never changing existing field types — new requirements get new fields, old ones are only removed after a full deprecation cycle."

Documentation explaining the differences between API versions and the steps required to upgrade, including code examples.

"The v2 migration guide lists every renamed field with a before/after code example — we measured adoption by tracking how many clients still hit v1 endpoints."

A structured description of what changed between API versions using the Added / Changed / Deprecated / Removed / Fixed format.

"The changelog entry for v2.3.0 lists 'Added: cursor-based pagination on GET /orders' and 'Deprecated: offset parameter' so consumers know exactly what changed."

The formal agreement between a provider and consumers specifying valid requests, expected responses, and error formats; often described in an OpenAPI specification.

"The OpenAPI spec is our API contract — before any change ships, the spec is updated first and reviewed by a consumer-impact team."

Testing approach where consumers define their expectations of a provider API; the provider's CI runs these consumer contracts to verify it does not break them.

"With Pact consumer-driven contracts, the mobile team's expected response shapes run in our backend CI — a breaking schema change fails the pipeline before it reaches production."

Returning partial data or a safe fallback when a dependency fails, rather than returning an error that forces the consumer to handle a failure case.

"When the recommendations service is down, the product page returns an empty recommendations array rather than a 503 — the consumer renders without recommendations gracefully."