api-versioning

Version a REST API by choosing a strategy such as URL path (/api/v1/users), query parameter, header, or media type versioning, then only make additive changes within a version. Reserve breaking changes like removing fields or changing types for a new major version with a migration guide.

URL path versioning is recommended for public APIs because it is highly visible, easy to route and cache, and simple for clients to implement. Header versioning suits internal APIs, while media type versioning fits enterprise environments requiring strict REST compliance.

Deprecate an API version through a phased lifecycle: announce with a migration guide, add Deprecation and Sunset HTTP headers, log usage by client, send warning notifications during the sunset period, then return 410 Gone responses after removal. Timelines range from 2 months for internal APIs to 18 months for enterprise.

GraphQL naturally supports additive changes without versioning by deprecating fields with the @deprecated directive instead of removing them. For true breaking changes, run separate endpoints such as /graphql and /graphql/v2 rather than versioning the schema.

Breaking changes include removing endpoints or response fields, changing field types, renaming fields, tightening validation rules, and changing authentication requirements. Safe changes include adding endpoints, optional parameters, new response fields, and new enum values when clients handle unknowns.