valec3 Backend API Versioning
When to use this skill
- Breaking changes
- Multiple API versions
- Backward compatibility
- Migration planning
Workflow
- Choose versioning strategy
- Version early
- Maintain old versions
- Deprecate gracefully
- Document changes
Instructions
URL Versioning
<?php
// Config/Routes.php
$routes->group('api/v1', ['namespace' => 'App\Controllers\API\V1'], function($routes) {
$routes->resource('users');
});
$routes->group('api/v2', ['namespace' => 'App\Controllers\API\V2'], function($routes) {
$routes->resource('users');
});
Header Versioning
<?php
$version = $this->request->getHeaderLine('Accept-Version') ?: 'v1';
Deprecation
<?php
return $this->respond($data)
->setHeader('X-API-Deprecated', 'This endpoint will be removed in v3')
->setHeader('X-API-Sunset', '2024-12-31');
Resources
- Version from day 1
- Maintain 2-3 versions max
- Communicate deprecations early