API versioning patterns in Laravel - Mini Project: Build & Apply

API Versioning Patterns in Laravel

📖 Scenario: You are building a Laravel API for a book store. You want to support multiple versions of the API so that old clients can still use version 1 while new clients use version 2 with improved features.

🎯 Goal: Create a simple Laravel API with two versions: v1 and v2. Each version should have a route that returns a list of books. Version 1 returns a basic list, and version 2 returns an enhanced list with extra details.

📋 What You'll Learn

Create a route group for API version 1 with prefix api/v1

Create a route group for API version 2 with prefix api/v2

Define a controller method for each version that returns a JSON list of books

Use Laravel routing and controller conventions for versioning

💡 Why This Matters

🌍 Real World

APIs often need to support multiple versions so that old apps keep working while new features are added. This project shows how to do that in Laravel.

💼 Career

Understanding API versioning is important for backend developers working with Laravel to build maintainable and scalable APIs.

1

Set up initial book data

Create a controller called BookController with a public method getBooksV1 that returns a JSON array with these exact books: ["The Hobbit", "1984", "Pride and Prejudice"].

Laravel

<?php

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class BookController extends Controller
{
    // Create public function getBooksV1 that returns JSON array of books
    // Your code here
}

Hint

Define a public method getBooksV1 inside BookController that returns the JSON array using response()->json().

2

Add API version 1 route group

In routes/api.php, add a route group with prefix v1. Inside it, define a GET route /books that uses BookController@getBooksV1.

Laravel

<?php

use Illuminate\Support\Facades\Route;

// Add route group with prefix 'v1' and GET route '/books' using BookController@getBooksV1
// Your code here

Hint

Use Route::prefix('v1')->group(function () { ... }); and inside define the GET route for /books.

3

Add version 2 controller method with enhanced data

In BookController, add a public method getBooksV2 that returns a JSON array of books with details. Use this exact array: [["title" => "The Hobbit", "author" => "J.R.R. Tolkien"], ["title" => "1984", "author" => "George Orwell"], ["title" => "Pride and Prejudice", "author" => "Jane Austen"]].

Laravel

group(function () {
    Route::get('/books', [App\Http\Controllers\BookController::class, 'getBooksV1']);
});

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class BookController extends Controller
{
    public function getBooksV1()
    {
        return response()->json(["The Hobbit", "1984", "Pride and Prejudice"]);
    }

    // Add public function getBooksV2 that returns JSON array with book title and author
    // Your code here
}

Hint

Define getBooksV2 method returning the detailed books array using response()->json().

4

Add API version 2 route group

In routes/api.php, add a route group with prefix v2. Inside it, define a GET route /books that uses BookController@getBooksV2.

Laravel

group(function () {
    Route::get('/books', [App\Http\Controllers\BookController::class, 'getBooksV1']);
});

// Add route group with prefix 'v2' and GET route '/books' using BookController@getBooksV2
// Your code here

namespace App\Http\Controllers;

use Illuminate\Http\Request;

class BookController extends Controller
{
    public function getBooksV1()
    {
        return response()->json(["The Hobbit", "1984", "Pride and Prejudice"]);
    }

    public function getBooksV2()
    {
        return response()->json([
            ["title" => "The Hobbit", "author" => "J.R.R. Tolkien"],
            ["title" => "1984", "author" => "George Orwell"],
            ["title" => "Pride and Prejudice", "author" => "Jane Austen"]
        ]);
    }
}

Hint

Use Route::prefix('v2')->group(function () { ... }); and inside define the GET route for /books using getBooksV2.

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