Overview
An API becomes a product once external clients depend on it. A change that looks small inside the server can break mobile apps, integrations or customer scripts. Versioning should be a deliberate compatibility policy, not a reaction after a release causes failures.
Prefer compatible evolution
Adding an optional response field is usually safer than renaming or removing an existing field. New request fields should have sensible defaults. Do not change the meaning, type or units of an existing field without treating it as a breaking change.
Choose a version boundary
Common approaches include a URL prefix such as /api/v1/, a media type, or a version header. A URL prefix is easy to inspect, route and document. Whichever approach you choose, apply it consistently to routing, documentation, tests and monitoring.
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
if (str_starts_with($path, '/api/v1/')) {
$apiVersion = 'v1';
} elseif (str_starts_with($path, '/api/v2/')) {
$apiVersion = 'v2';
} else {
http_response_code(404);
exit;
}
Keep version selection separate from business logic. Shared services can implement common rules while version-specific controllers adapt request and response formats.
Deprecation process
When a version is scheduled for retirement, publish the date, migration guidance and replacement endpoints. Where appropriate, return deprecation and sunset information in response headers. Give clients a realistic migration window and monitor actual usage before disabling a version.
Test contracts
Maintain request and response examples for each supported version. Contract tests should detect accidental changes to field names, types, status codes and error formats. Test old clients against the new deployment, not only the newest client.
Checklist
- Document what counts as a breaking change.
- Keep version routing explicit.
- Separate version adapters from core business services.
- Publish deprecation dates and migration notes.
- Measure traffic by API version and client.
- Retire old versions only after communicating and reviewing usage.