API versioning and schema evolution without client surprises

An API change is breaking when an existing consumer can no longer make a valid request or interpret a valid response. Removing a field, changing a type, tightening validation, changing a status code, or altering retry semantics can break a client even when the URL and method remain the same. Start with an inventory of consumers and the decisions each one makes from the contract. Your own frontend is only one consumer; integrations and saved scripts may live outside your repository.

Define whether the API promises backward compatibility, a sunset date, or a versioned migration. A promise is useful only when the team can observe usage and communicate changes. Keep the contract in an API description and in tests, but also document the behavior that a schema cannot express, such as idempotency and eventual consistency.

Adding an optional response field is usually compatible, but some clients reject unknown fields or deserialize into a strict type. Adding an enum value can break a switch statement that assumes the list is closed. Making a previously optional request field required is breaking even if the database can accept it. Treat every additive change as a hypothesis to verify against real clients and generated SDKs.

Use tolerant readers and explicit defaults where the product allows it. Do not silently treat an unknown security or billing state as a safe value. For critical enums, provide an unknown branch that fails closed or routes to a review path. A compatibility test should include a client built from the previous contract consuming the new response.

URL versions are visible and easy to route, while header or media-type versions can keep URLs stable but require more tooling and debugging discipline. A separate endpoint may be appropriate for a fundamentally different workflow. Do not create a new version for every field change; version when the contract or behavior needs a distinct compatibility window. Keep the number of active versions bounded and assign an owner to each.

A version should select a complete behavior contract, not only a serializer. Authentication, pagination, error codes, rate limits, and side-effect semantics may need to remain compatible too. Put version selection at the edge or adapter boundary and expose the selected version in safe diagnostics. A request that accidentally falls back to the default version can be more dangerous than an explicit unsupported-version error.

Give consumers time to migrate. Document the replacement, announce the timeline, add a deprecation response header or warning where appropriate, and measure usage by version and operation. Do not log a warning for every request without an owner; that creates noise. A dashboard that shows remaining consumers and last-seen dates is more actionable.

A sunset date should include the timezone, migration guide, support channel, and rollback expectation. Continue serving the old contract only while it remains safe and affordable. If a security issue requires faster removal, communicate the risk and provide a temporary compatibility proxy or explicit failure path. A silent hard cut is rarely the safest migration.

An API version often spans a database or event schema. Use expand-and-contract migrations so old and new handlers can coexist. A new response field may require a backfill, while a renamed request field may need dual-read and dual-write behavior. Do not remove a database column merely because the new API route no longer references it; an old worker or external client may still do so.

For events, keep the original type and add a version or a new event contract. Consumers should be able to ignore unknown fields but must not silently misinterpret a changed meaning. Record the producer and consumer versions in telemetry. An event already in a queue can outlive the deployment that produced it, so compatibility lasts longer than an HTTP request.

Build contract tests from the previous version's client and run them against the candidate server. Include malformed input, unknown fields, status codes, headers, pagination cursors, authentication failures, and retry behavior. For high-value integrations, keep a live probe in a sandbox and a recorded fixture for edge cases. Verify that a rollback server can still read data written by the new version.

Test mixed-version traffic during a rolling deploy. Send old and new requests concurrently, publish old and new events, and run background jobs that have not been updated yet. Observe whether metrics and logs identify the contract version. A green test against only the new client cannot prove a safe migration.

Track requests by version, deprecated operation, client identity, error category, and migration status. Alert before a sunset date when usage remains. Keep a support playbook for a consumer that cannot migrate on time, and define the security owner for an exception. Remove old code, schemas, fixtures, and documentation after the final consumer is gone so the team does not keep maintaining a ghost contract.

API evolution is successful when consumers can change at their own pace without the service carrying indefinite ambiguity. Prefer additive changes, define a real version boundary, signal deprecation, coordinate data migrations, test mixed versions, and publish a removal record. Compatibility is a product feature and an operational responsibility.

Before removing a version, prove that the last consumer is gone through server metrics, provider confirmation, and background-job inspection. Stop new usage first, keep a short observation window, and return an explicit unsupported-version response after the sunset. Remove old serializers and data fallbacks only after a rollback target no longer depends on them.

Keep migration notes beside the contract and link them from the deprecation response. Include examples of old and new requests, status changes, pagination or cursor behavior, and the support deadline. A consumer should be able to plan its update without reading your internal implementation.

Keep a compatibility layer at the API boundary so internal models can evolve without forcing every client to update simultaneously. Validate old and new payloads, document nullability and enum behavior, and preserve pagination semantics during the transition. Measure usage by version and consumer, then announce a removal date with an explicit unsupported response. This lets the team improve implementation details while honoring the contract that external developers actually depend on.

Put a compatibility layer at the API boundary and define additive, deprecated, and breaking changes explicitly. Preserve nullability, enum, pagination, error, and version semantics during the overlap. Measure usage by version and consumer, announce a sunset date, and return an explicit unsupported-version response after the deadline.

Run old and new contract fixtures, unknown fields, missing nullable fields, enum additions, pagination boundaries, authentication failures, and rollback traffic through both serializers. Track version usage, consumer identity, error rate, and response shape. A schema change is not compatible merely because the server can parse one sample request.

Stop new usage before removal, keep a bounded observation window, and verify background jobs and providers have migrated. Keep old serializers until no rollback target depends on them. If a breaking release causes impact, route clients to the previous version or adapter and preserve the migration record rather than silently changing the contract again.

Use semantic versioning, OpenAPI or JSON Schema compatibility guidance, and the provider's deprecation policy. Document consumer deadline, migration examples, and unsupported-version behavior in the public contract.