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.

Practice

1. Which of the following is a common pattern for API versioning in Laravel?

easy

A. Changing database schema for each API version

B. Using URL prefixes like /api/v1/ to separate versions

C. Using different PHP files for each API version

D. Hardcoding version numbers inside controller methods

Solution

1. Step 1: Understand common API versioning methods

   API versioning often uses URL prefixes, query parameters, or headers to separate versions.

2. Step 2: Identify Laravel's typical approach

   Laravel commonly uses route groups with URL prefixes like /api/v1/ to manage versions cleanly.

3. Final Answer:

   Using URL prefixes like /api/v1/ to separate versions -> Option B

4. Quick Check:

   URL prefix versioning = A [OK]

Hint: Look for URL prefix usage in routes for versioning [OK]

Common Mistakes:

• Confusing database changes with API versioning
• Thinking versioning requires separate PHP files
• Embedding version logic inside controllers

2. Which is the correct way to define a versioned API route group in Laravel using URL prefix?

easy

A. Route::version('v1')->group(function () { Route::get('/users', ...); });

B. Route::apiVersion('v1', function () { Route::get('/users', ...); });

C. Route::prefix('v1')->group(function () { Route::get('/users', ...); });

D. Route::group('version:v1', function () { Route::get('/users', ...); });

Solution

1. Step 1: Recall Laravel route group syntax

   Laravel uses Route::prefix('prefix')->group(function() {...}) to group routes under a URL prefix.

2. Step 2: Match versioning syntax

   Using prefix('v1') correctly sets the URL prefix for version 1 routes.

3. Final Answer:

   Route::prefix('v1')->group(function () { Route::get('/users', ...); }); -> Option C

4. Quick Check:

   Route prefix method = B [OK]

Hint: Remember Laravel uses prefix() for URL grouping [OK]

Common Mistakes:

• Using non-existent methods like version() or apiVersion()
• Passing version as a string to group() directly
• Confusing middleware with prefix for versioning

3. Given this Laravel route group:

Route::prefix('api/v2')->group(function () {
    Route::get('/products', function () {
        return 'Version 2 Products';
    });
});

What will be the response when accessing /api/v2/products?

medium

A. "Version 2 Products"

B. 404 Not Found error

C. "Version 1 Products"

D. 500 Internal Server Error

Solution

1. Step 1: Analyze the route prefix and path

   The route is grouped under prefix api/v2 and defines a GET route for /products.

2. Step 2: Match the URL to the route

   Accessing /api/v2/products matches this route and returns the string 'Version 2 Products'.

3. Final Answer:

   "Version 2 Products" -> Option A

4. Quick Check:

   Route prefix + path = Version 2 Products [OK]

Hint: Match full URL with prefix + route path [OK]

Common Mistakes:

• Assuming version 1 response without checking prefix
• Expecting error due to missing controller
• Confusing route path with prefix

4. What is wrong with this Laravel API versioning route definition?

Route::group(['prefix' => 'api/v1'], function () {
    Route::get('/users', 'UserController@index');
});
Route::group(['prefix' => 'api/v1'], function () {
    Route::get('/users', 'UserController@list');
});

medium

A. Route groups cannot share the same prefix

B. Prefix should be 'v1/api' not 'api/v1'

C. Controller methods must be named 'show' or 'index' only

D. Duplicate routes with same URL and method cause conflicts

Solution

1. Step 1: Identify route conflicts

   Both route groups define GET routes for /api/v1/users but point to different controller methods.

2. Step 2: Understand Laravel routing behavior

   Laravel cannot distinguish between these two identical routes, causing conflicts or unexpected behavior.

3. Final Answer:

   Duplicate routes with same URL and method cause conflicts -> Option D

4. Quick Check:

   Duplicate route URLs = conflict [OK]

Hint: Avoid duplicate routes with same method and path [OK]

Common Mistakes:

• Thinking prefix order matters for routing
• Believing controller method names are restricted
• Assuming route groups cannot share prefixes

5. You want to support two API versions in Laravel: v1 and v2. Version 1 returns all users, version 2 returns only active users. Which is the best way to organize routes and controllers?

hard

A. Use route groups with prefixes /api/v1 and /api/v2, each pointing to separate controllers handling version logic

B. Use a single route /api/users and check version in controller to return different data

C. Use query parameter ?version=1 and switch logic inside one controller method

D. Create separate Laravel projects for each API version

Solution

1. Step 1: Understand maintainability and clarity

   Separating versions by route prefix and controllers keeps code clean and easy to maintain.

2. Step 2: Evaluate other options

   Single route with version checks or query parameters mixes logic and complicates code. Separate projects add unnecessary overhead.

3. Final Answer:

   Use route groups with prefixes /api/v1 and /api/v2, each pointing to separate controllers handling version logic -> Option A

4. Quick Check:

   Separate prefixes + controllers = clean versioning [OK]

Hint: Group routes by prefix and separate controllers per version [OK]

Common Mistakes:

• Mixing version logic inside one controller
• Using query parameters for versioning in Laravel routes
• Splitting versions into separate projects unnecessarily