API versioning patterns in Laravel

Introduction

API versioning helps keep your app working well when you add new features or change things. It lets old and new users use the API without problems.

You want to add new features to your API without breaking old apps.

You need to fix bugs or improve your API but keep old versions working.

You want to support different clients that need different API versions.

You plan to change how your API works but want a smooth upgrade path.

You want to organize your API code clearly by version.

Syntax

Laravel

<?php

use Illuminate\Support\Facades\Route;

// URL versioning example
Route::prefix('api/v1')->group(function () {
    Route::get('/users', [UserControllerV1::class, 'index']);
});

// Header versioning example
Route::middleware('api.version:v1')->group(function () {
    Route::get('/users', [UserControllerV1::class, 'index']);
});

URL versioning uses the version in the API path like /api/v1/.

Header versioning uses a custom header to specify the version, requiring middleware to check it.

Examples

This groups routes under /api/v2/ so clients call the new version by URL.

Laravel

<?php

// URL versioning
Route::prefix('api/v2')->group(function () {
    Route::get('/products', [ProductControllerV2::class, 'list']);
});

Clients add ?version=1 to the URL to specify the API version.

Laravel

<?php

// Query parameter versioning
Route::get('/orders', [OrderController::class, 'index']);
// Client calls /orders?version=1

This uses a middleware to route requests based on a custom header value.

Laravel

<?php

// Header versioning middleware example
// Middleware checks 'Accept-Version' header
Route::middleware('api.version:v2')->group(function () {
    Route::get('/customers', [CustomerControllerV2::class, 'index']);
});

Sample Program

This example shows two API versions using URL prefixes. Version 1 returns two users, version 2 returns three users. Clients choose version by URL.

Laravel

<?php

use Illuminate\Support\Facades\Route;
use App\Http\Controllers\UserControllerV1;
use App\Http\Controllers\UserControllerV2;

// API version 1 routes
Route::prefix('api/v1')->group(function () {
    Route::get('/users', [UserControllerV1::class, 'index']);
});

// API version 2 routes
Route::prefix('api/v2')->group(function () {
    Route::get('/users', [UserControllerV2::class, 'index']);
});

// UserControllerV1.php
namespace App\Http\Controllers;

class UserControllerV1 {
    public function index() {
        return response()->json(['version' => 'v1', 'users' => ['Alice', 'Bob']]);
    }
}

// UserControllerV2.php
namespace App\Http\Controllers;

class UserControllerV2 {
    public function index() {
        return response()->json(['version' => 'v2', 'users' => ['Alice', 'Bob', 'Charlie']]);
    }
}

Important Notes

URL versioning is simple and easy to test in browsers.

Header or query versioning keeps URLs clean but needs extra code to detect versions.

Keep old API versions for a while to avoid breaking users.

Summary

API versioning helps manage changes without breaking old clients.

Common patterns include URL prefix, query parameter, and header versioning.

Laravel routes can be grouped by version using prefixes or middleware.