API versioning patterns in Laravel - Step-by-Step Execution

Concept Flow - API versioning patterns

Client sends API request

↓

Check version info in request

↓

URL

↓

Route request to correct versioned controller

↓

Process request and send response

The API receives a request, detects the version from URL, header, or query, then routes to the matching version controller to respond.

Execution Sample

Laravel

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

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

Defines two API versions using URL prefixing, routing requests to different controllers based on version.

Execution Table

Step	Request URL	Version Detected	Controller Called	Response Behavior
1	/api/v1/users	v1 (from URL prefix)	UserControllerV1@index	Returns user list in v1 format
2	/api/v2/users	v2 (from URL prefix)	UserControllerV2@index	Returns user list in v2 format with extra fields
3	/api/users?version=1	v1 (from query param)	UserControllerV1@index	Returns user list in v1 format
4	/api/users	default version (v1)	UserControllerV1@index	Returns user list in v1 format
5	/api/users	header X-API-Version: 2	UserControllerV2@index	Returns user list in v2 format
6	/api/v3/users	No route defined	404 Not Found	Error response - version not supported

💡 Requests stop after routing to the correct controller or returning error if version unsupported.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4	After Step 5	Final
version	null	v1	v2	v1	v1	v2	null
controller	null	UserControllerV1@index	UserControllerV2@index	UserControllerV1@index	UserControllerV1@index	UserControllerV2@index	null
response	null	v1 user list	v2 user list	v1 user list	v1 user list	v2 user list	error or user list

Key Moments - 3 Insights

How does Laravel know which API version to use when the version is in the URL?

Laravel uses route groups with prefixes like 'api/v1' or 'api/v2' to detect the version from the URL and route to the matching controller, as shown in execution_table rows 1 and 2.

What happens if the client does not specify a version in the request?

Laravel routes to a default version controller, often the first version, as shown in execution_table row 4 where no version is in URL or headers, so v1 controller is used.

Can API versioning be done using HTTP headers instead of URL?

Yes, Laravel can check headers like 'X-API-Version' to decide the version, routing accordingly as in execution_table row 5.

Visual Quiz - 3 Questions

Look at the execution table, which controller handles the request to '/api/v2/users'?

A UserControllerV1@index

B UserControllerV3@index

C UserControllerV2@index

D 404 Not Found

💡 Hint

Check the row where Request URL is '/api/v2/users' in the execution_table.

At which step does the request return a 404 error due to unsupported version?

A Step 3

B Step 6

C Step 4

D Step 1

💡 Hint

Look for the row with 'No route defined' in the Version Detected column.

If the client sends '/api/users' with header 'X-API-Version: 2', which version is used?

A v2

B v1

C default (v1)

D No version detected

💡 Hint

See the execution_table row where header 'X-API-Version: 2' is used.

Concept Snapshot

API versioning in Laravel routes requests based on version info.
Common patterns:
- URL prefix (e.g., /api/v1)
- Query parameter (e.g., ?version=1)
- HTTP header (e.g., X-API-Version)
Routes map to versioned controllers.
Default version used if none specified.

Full Transcript

API versioning patterns in Laravel help manage different versions of an API. The client sends a request with version info in the URL, query, or header. Laravel detects this version and routes the request to the matching controller. For example, URL prefixing uses route groups like 'api/v1' or 'api/v2' to separate versions. If no version is specified, a default version controller handles the request. This approach allows maintaining multiple API versions simultaneously and evolving the API without breaking existing clients.

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