URL-path or header-based versioning?

URL-path (/v1/resource) is the most common and explicit approach. It is easier for consumers to discover and test. Header-based is cleaner but less visible. Default to URL-path unless you have a specific reason not to.

How many API versions should I support simultaneously?

Two to three at most. Supporting more creates maintenance burden. Set clear sunset dates and actively migrate consumers off old versions.

When should I create a new major version?

Only for breaking changes that cannot be made backward-compatible: removing fields, changing response structures, or altering authentication. Most changes can be additive and do not require a new version.

API Versioning Checklist

Ship new API versions without breaking existing consumers. A structured checklist for versioning strategy, deprecation, and migration.

Checklist: API Versioning (engineering)

API versioning is the discipline of evolving your API while maintaining backward compatibility for existing consumers. Without a deliberate strategy, breaking changes cause integration failures, customer churn, and engineering firefights. This checklist covers strategy selection, implementation, deprecation policies, and consumer communication.

Checklist Items

Choose a versioning strategy [critical]: Select URL-path (/v1/), header-based, or query parameter versioning. Document the reasoning and commit to it.
Define backward compatibility rules [critical]: Specify what constitutes a breaking change: field removal, type changes, behavior changes, and status code modifications.
Implement version routing in the API gateway [critical]: Configure routing so each version maps to the correct handler while sharing common middleware.
Create a deprecation policy [important]: Define minimum deprecation notice period (e.g., 6 months), communication channels, and sunset header standards.
Add Sunset and Deprecation response headers [important]: Include standard HTTP headers that inform consumers of upcoming deprecation dates on old versions.
Maintain a changelog for each version [important]: Document every change per version with added, changed, deprecated, and removed categories.
Version your API documentation separately [important]: Generate and host docs per version so consumers can reference the correct specification for their integration.
Add contract tests between versions [recommended]: Automated tests that verify the old version contract is not broken by new version changes.
Monitor version usage analytics [recommended]: Track which consumers use which versions to inform deprecation timelines and identify stragglers.
Create migration guides for major versions [recommended]: Provide step-by-step migration documentation with before/after examples for each breaking change.

Common Mistakes

Versioning too aggressively: Use additive changes wherever possible. New optional fields, new endpoints, and new enum values do not require a new version.
No deprecation period: Never sunset a version without at least 3-6 months notice. Give consumers time to migrate with clear documentation.
Inconsistent versioning across endpoints: Version the entire API uniformly. Mixing versioned and unversioned endpoints creates confusion and integration bugs.

Frequently Asked Questions

URL-path or header-based versioning?: URL-path (/v1/resource) is the most common and explicit approach. It is easier for consumers to discover and test. Header-based is cleaner but less visible. Default to URL-path unless you have a specific reason not to.
How many API versions should I support simultaneously?: Two to three at most. Supporting more creates maintenance burden. Set clear sunset dates and actively migrate consumers off old versions.
When should I create a new major version?: Only for breaking changes that cannot be made backward-compatible: removing fields, changing response structures, or altering authentication. Most changes can be additive and do not require a new version.