Laravel Tutorials

API Versioning in Laravel 11

Published
API Versioning in Laravel 11 image

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!

Paul Redmond photo

Staff writer at Laravel News. Full stack web developer and author.

Sponsored

serpapi logo
SerpApi

The Web Search API for Your LLM and AI Applications

Visit SerpApi

The latest

View all →
Laravel AI SDK 1.4 Lets Agents Recover From Tool Failures image

Laravel AI SDK 1.4 Lets Agents Recover From Tool Failures

Read article
Laravel Read Replicas: Check if a Replica Has Caught Up image

Laravel Read Replicas: Check if a Replica Has Caught Up

Read article
UUID Request Input and Migration Failure Events in Laravel 13.42 image

UUID Request Input and Migration Failure Events in Laravel 13.42

Read article
Replay Missed Laravel Scheduled Tasks With Schedule Catchup image

Replay Missed Laravel Scheduled Tasks With Schedule Catchup

Read article
Search Polymorphic Relations and Filament Tables With Laravel Searchable image

Search Polymorphic Relations and Filament Tables With Laravel Searchable

Read article
Laravel Rest Api 3.0: Typed Fields, Metrics, and OpenAPI Docs image

Laravel Rest Api 3.0: Typed Fields, Metrics, and OpenAPI Docs

Read article