API Versioning
API versioning is the practice of maintaining identifiable versions of an API so its behaviour can evolve without unexpectedly breaking existing integrations.
A version creates a defined contract an integration can build against.
Why APIs Change
An API may eventually need to:
- Rename a field
- Remove an operation
- Change Authentication
- Add required information
- Change how a response works
- Replace an older data model
Some additions can be made without breaking existing integrations.
Others cannot.
How Versioning Works
Providers may represent versions through:
- URL paths
- Request headers
- Dates
- Query parameters
- Versioned SDKs
There is no single universal approach.
GitHub's REST API uses explicit dated versions and documents breaking changes separately from additive changes. GitHub REST API versioning documentation
Why It Matters
Without versioning, a provider changing:
customer_nameto:
full_namecould unexpectedly break every integration expecting the old field.
A versioned API can provide a migration period.
Deprecation
API providers may eventually deprecate old versions or endpoints.
A deprecated version may:
- Continue working temporarily
- Stop receiving new features
- Receive a scheduled retirement date
- Eventually be removed
Integrations therefore require some ongoing Maintenance.
Common Problems
Common problems include:
- Integration does not specify a version
- Nobody monitors provider announcements
- Deprecated endpoints remain in production
- Breaking changes discovered only after failure
- Developers update the API version without testing
- Documentation does not record which version is used
How to Improve
Document the API version used by the integration.
Monitor provider notices, review breaking changes before upgrading, and test version changes before deployment.
API integrations are operational dependencies, not permanent set-and-forget connections.