API Versioning in Laravel 11

With the release of Laravel 11, the application skeleton was slimmed down to remove extra files that aren't required on every project. Part of that change removed all service providers from the application source code except the AppServiceProvider.

Another part of the updated application skeleton is removing API routes in the default installation. Suppose you plan on adding an API to your application or exclusively writing an API with Laravel. In that case, you can set up the api middleware group and routes with an Artisan command:

php artisan install:api

The install:api sets up the api.php route file (and configures it), a database migration for personal access tokens, and a sanctum configuration file. If you don't need to version your API, that's all you need to do.

#Versioning Your API in Separate Files

A common approach to writing versioned APIs in Laravel is separating routes into different files. Doing so simplifies the overhead of reasoning about a specific API version and keeps things tidy. In Laravel 10 or earlier, a common approach is adding additional route files for each API version to the RouteServiceProvider:

$this->routes(function () {
    Route::middleware('api')
        ->prefix('api')
        ->group(base_path('routes/api.php'));
 
    Route::middleware('api')
        ->prefix('api/v1')
        ->group(base_path('routes/api_v1.php'));
 
    Route::middleware('api')
        ->prefix('api/v2')
        ->group(base_path('routes/api_v2.php'));
 
    Route::middleware('web')
        ->group(base_path('routes/web.php'));
});

In the above example, the routes/api.php typically offers a /user endpoint for Laravel sanctum, and the remainder of API routes are tucked in the appropriate version.

#Versioning Your API in Laravel 11

With route bootstrapping moving out of the RouteServiceProvider and into bootstrap/app.php, here are a few ways you can version your API.

First, let's generate a few files to demonstrate setting up routing:

touch routes/api_v1.php
touch routes/api_v2.php
 
php artisan make:controller --api Api/V1/PostsController
php artisan make:controller --api Api/V2/PostsController

Use whatever file name convention and location that suits you.

Next, open the routes/api.php file and add the following lines to the bottom of the file:

Route::prefix('v1')->group(base_path('routes/api_v1.php'));
Route::prefix('v2')->group(base_path('routes/api_v2.php'));

The above code being in api.php means that we are already working within the api route prefix and using the api middleware group.

Next, let's add the example routes for each respective API version so we can visualize the route list for each version.

Here's the api_v1.php file:

<?php
 
use App\Http\Controllers\Api\V1\PostsController;
 
Route::apiResource('posts', PostsController::class);

And the api_v2.php file:

<?php
 
use App\Http\Controllers\Api\V2\PostsController;
 
Route::apiResource('posts', PostsController::class);

With our route files defined, running route:list, we can see versioned routes!

Pro tip: you can isolate versioned routes using the --path flag, making it easy to focus on a specific API version:

php artisan route:list --path=api/v1
php artisan route:list --path=api/v2

Check out how tidy it looks if you just output routes for api/v2:

#Defining Versioned Routes in the App Bootstrap File

Another approach I've seen is defining additional API routes in the bootstrap/app.php file using the then: argument, which accepts a Closure:

return Application::configure(basePath: dirname(__DIR__))
    ->withRouting(
        web: __DIR__.'/../routes/web.php',
        api: __DIR__.'/../routes/api.php',
        commands: __DIR__.'/../routes/console.php',
        health: '/up',
        then: function () {
            Route::middleware('api')
                ->prefix('api/v1')
                ->group(base_path('routes/api/api_v1.php'));
 
            Route::middleware('api')
                ->prefix('api/v2')
                ->group(base_path('routes/api/api_v2.php'));
        }
    )
    // ...
;

I prefer adding additional route files directly to routes/api.php, but this is another approach that would work. When defining routes in the bootstrap file, these groups aren't configured to use the api middleware group. Make sure to include the api middleware group with these routes!