API Versioning in Laravel

When you build an API, you may need to update or improve it over time. But if you make big changes, it can break things for people already using your API. Versioning allows you to create multiple versions of your API, so old versions still work even after you make updates.

When should you use versioning?

You should version your API if:

1. Future updates — if you expect to release updates later, versioning keeps things organised.
2. Major changes — if you plan to change something big, like the shape of the data you return, versioning makes sure old versions still work for existing users.

By versioning, you can keep improving your API without breaking it for anyone who relies on older versions.

How to set up API versioning in Laravel

Step 1: Change the default route setup

In Laravel, we can organise our routes based on version numbers. To do this, go to the RouteServiceProvider file located in App\Providers.

In Laravel 8 and above, add this line to define a namespace for your API controllers:

protected string $ApiNamespace = 'App\Http\Controllers\Api';

Now, in the boot method, set up different routes for each API version:

$this->routes(function () {
    // Version 1 routes
    Route::prefix('api/v1')
        ->middleware('api')
        ->namespace($this->ApiNamespace . '\\V1')
        ->group(base_path('routes/API/v1.php'));

    // Version 2 routes
    Route::prefix('api/v2')
        ->middleware('api')
        ->namespace($this->ApiNamespace . '\\V2')
        ->group(base_path('routes/API/v2.php'));
});

Now, when you visit /api/v1/... it uses the controllers in the V1 folder, and /api/v2/... uses the V2 folder.

Step 2: Organise your controllers by version

Inside App\Http\Controllers\Api, create a folder for each version, so you end up with something like this:

Controllers
└── Api
    ├── V1
    │   └── TimeSlotController.php
    └── V2
        └── TimeSlotController.php

Now you can have different versions of the same controller, like TimeSlotController, for each API version. If you change something in version 2, version 1 stays exactly as it was.

Step 3: Create separate route files for each version

In the routes folder, create a file for each version of your API routes:

routes
└── Api
    ├── v1.php
    ├── v2.php
└── web.php

Each version file (v1.php and v2.php) holds the routes specific to that version.

For example, in routes/API/v1.php:

Route::post('/timeslots', [App\Http\Controllers\Api\V1\TimeSlotController::class, 'getSlots']);

And in routes/API/v2.php:

Route::post('/timeslots', [App\Http\Controllers\Api\V2\TimeSlotController::class, 'getSlots']);

With this setup, you can update or change routes for each version independently.

In short

Versioning your API keeps it flexible and reliable. By setting up separate folders for routes and controllers for each version, you make sure that changes don't break things for existing users. Versioning is a good way to grow an API without causing problems for the people who depend on it.