How to Version API in Laravel: Simple Guide with Examples

In Laravel, you version your API by grouping routes with version prefixes like v1 or v2 in your routes/api.php file. You then create separate controllers or methods for each version to keep your API organized and maintainable.

Syntax

API versioning in Laravel is done by grouping routes under a version prefix. This is usually done in the routes/api.php file using the Route::prefix() method. Each version can have its own controller or method to handle requests.

• Route::prefix('v1'): Groups routes under the URL prefix /api/v1.
• Route::group(): Groups multiple routes together.
• Controller@method: Specifies which controller and method handle the request.

php

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

Example

This example shows two API versions: v1 and v2. Each version has its own route group and controller. When you call /api/v1/users, it uses UserControllerV1. When you call /api/v2/users, it uses UserControllerV2. This keeps your API versions separate and easy to maintain.

php

<?php

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

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

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

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

use Illuminate\Http\Request;

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

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

use Illuminate\Http\Request;

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

Output

{"version":"v1","users":["Alice","Bob"]} (for /api/v1/users) or {"version":"v2","users":["Alice","Bob","Charlie"]} (for /api/v2/users)

Common Pitfalls

Common mistakes when versioning APIs in Laravel include:

• Not using route prefixes, which makes versions hard to distinguish.
• Mixing logic for different versions in the same controller, causing confusion and bugs.
• Forgetting to update API documentation to reflect version changes.

Always keep version logic separated and clearly documented.

php

/* Wrong: Mixing versions in one controller without prefixes */
Route::get('/users', [UserController::class, 'index']);

/* Right: Separate versions with prefixes and controllers */
Route::prefix('v1')->group(function () {
    Route::get('/users', [UserControllerV1::class, 'index']);
});

Quick Reference

Concept	Description
Route Prefix	Use Route::prefix('v1') to group routes by version.
Separate Controllers	Create different controllers like UserControllerV1 and UserControllerV2.
Route Grouping	Group routes inside Route::group() for cleaner code.
API URL	Access versions via URLs like /api/v1/users and /api/v2/users.
Documentation	Keep API docs updated for each version.

Key Takeaways

Use route prefixes like 'v1' and 'v2' to version your API URLs in Laravel.

Create separate controllers for each API version to keep code organized.

Group versioned routes using Route::prefix() and Route::group() for clarity.

Avoid mixing different API versions in the same controller or route.

Always update your API documentation to reflect version changes.