API Versioning Strategies: Planning for Evolution

APIs Must Evolve

Your API will change. New features, bug fixes, performance improvements—change is inevitable. Good versioning strategies let you evolve without breaking existing integrations.

Versioning Approaches

URL Path Versioning

// Most explicit and common
Route::prefix('api/v1')->group(function () {
    Route::apiResource('orders', V1\OrderController::class);
});

Route::prefix('api/v2')->group(function () {
    Route::apiResource('orders', V2\OrderController::class);
});

Header Versioning

// Cleaner URLs, less visible
// Accept: application/vnd.api+json; version=2

class ApiVersionMiddleware
{
    public function handle(Request $request, Closure $next)
    {
        $version = $this->extractVersion($request);
        $request->attributes->set('api_version', $version);

        return $next($request);
    }
}

Query Parameter Versioning

// /api/orders?version=2
// Simple but clutters URLs

Backward Compatibility

// Add new fields without breaking existing clients
class OrderResource extends JsonResource
{
    public function toArray($request): array
    {
        $data = [
            'id' => $this->id,
            'total' => $this->total,
            'status' => $this->status,
        ];

        // New field, doesn't break existing clients
        if ($request->attributes->get('api_version') >= 2) {
            $data['estimated_delivery'] = $this->estimated_delivery;
        }

        return $data;
    }
}

Deprecation Strategy

class DeprecationMiddleware
{
    public function handle(Request $request, Closure $next)
    {
        $response = $next($request);

        if ($this->isDeprecatedVersion($request)) {
            $response->headers->set('Deprecation', 'true');
            $response->headers->set('Sunset', '2025-01-01');
            $response->headers->set(
                'Link',
                '; rel="successor-version"'
            );
        }

        return $response;
    }
}

Version Documentation

/**
 * @group Orders
 * @version 2.0
 * @deprecated Use v3 endpoint instead
 *
 * @response 200 {
 *   "data": {"id": 1, "total": 99.99}
 * }
 */
public function index(): OrderCollection
{
    return new OrderCollection(Order::paginate());
}

Conclusion

Choose a versioning strategy early and be consistent. URL versioning is most explicit. Maintain backward compatibility as long as practical, and provide clear deprecation timelines.