API Versioned Route Support

[ShaungBhone]

RFC: API Versioned Route Support

• Proposal: Add native support for API Versioned Routing in Laravel
• Author: ShaungBhone
• Status: Draft
• Created: 2025-06-14

Overview

Currently, Laravel provides robust routing capabilities, but there is no native, first-class support for versioning API routes. Developers often rely on manual solutions, third-party packages, or custom middleware to handle versioning. This RFC proposes to introduce a built-in, elegant way to define and manage versioned API routes in Laravel.

Motivation

• Consistency: Ensures all Laravel applications can use a standardized approach for API versioning.
• Maintainability: Reduces boilerplate and makes it easier to deprecate or update API versions.
• Discoverability: Makes it clear which versions are available and which controllers handle which versions.

Proposed Implementation

New Routing Syntax

Add a version() routing method to the router, allowing grouping of routes by API version:

Route::prefix('api')->group(function () {
    Route::version('v1', function () {
        Route::get('users', [V1\UserController::class, 'index']);
    });
    Route::version('v2', function () {
        Route::get('users', [V2\UserController::class, 'index']);
    });
});

This would automatically prefix routes with the version and allow for grouping by version.

Example Resulting Routes

Method	URI	Action
GET	api/v1/users	V1\UserController@index
GET	api/v2/users	V2\UserController@index

Route Version Detection

Optionally, allow API version to be determined by:

• URL prefix (default, e.g., /api/v1/...)
• Header (e.g., Accept: application/vnd.yourapp.v1+json)
• Query parameter (e.g., ?version=1)

Provide a middleware or configuration option to choose the strategy.

Route Caching

Ensure that versioned routes are compatible with Laravel’s existing route caching system.

Deprecation Support

Allow marking versions as deprecated to aid documentation and sunset planning:

Route::version('v1', ['deprecated' => true], function () {
    // ...
});

Backward Compatibility

The new versioned routing is opt-in and does not break existing applications. All current routing remains unchanged if the new method is not used.

Drawbacks

• Adds complexity to the router.
• Developers may still require custom logic for highly customized version strategies.

Alternatives

• Continue using custom prefixes or third-party packages.
• Middleware-based version switching.
• Use subdomains for versioning (less common).

Open Questions

• Should header/query parameter-based versioning be included in core, or as an official package?
• How should documentation and route list (php artisan route:list) display deprecated routes?

Unresolved Issues

• Final design of middleware or configuration for version detection.
• Extending support for resource routes and route model binding.

Conclusion

Adding native API versioned routing to Laravel will provide a standardized, maintainable, and discoverable way for developers to manage multiple API versions, improve developer experience, and reduce reliance on third-party packages or custom code.

[shaedrich]

Deprecation Support

Allow marking versions as deprecated to aid documentation and sunset planning:

Route::version('v1', ['deprecated' => true], function () {
    // ...
});

I wouldn't do this via an array.

Flag arguments:

Route::version('v1', deprecated: true, function () {
    // ...
});

Methods

Route::version('v1', function () {
    // ...
})->deprecated();

Should header/query parameter-based versioning be included in core, or as an official package?

If not,

Add a version() routing method to the router, allowing grouping of routes by API version:

Route::prefix('api')->group(function () {
    Route::version('v1', function () {
        Route::get('users', [V1\UserController::class, 'index']);
    });
    Route::version('v2', function () {
        Route::get('users', [V2\UserController::class, 'index']);
    });
});

This would automatically prefix routes with the version and allow for grouping by version.

Example Resulting Routes

Method	URI	Action
GET	api/v1/users	V1\UserController@index
GET	api/v2/users	V2\UserController@index

will be exactly the same as

Route::prefix('api')->group(function () {
    Route::prefix('v1', function () {
        Route::get('users', [V1\UserController::class, 'index']);
    });
    Route::prefix('v2', function () {
        Route::get('users', [V2\UserController::class, 'index']);
    });
});

Route Version Detection

Via Subdomain might also be an option

How should documentation and route list (php artisan route:list) display deprecated routes?

Why not? This can include

• an extra column, marking that row as deprecated
• a filter to include or exclude deprecated routes (you would probably also want a version filter or some grouping)

[henzeb]

I'd ditch the v there and addan option to change the format?

[shaedrich]

Not only the format might differ. There might be APIs with tokens that have an embedded version that can't be extracted without decoding them first or so.

[ShaungBhone]

[Edited] New Routing Syntax

Add a version() routing method to the router, allowing grouping of routes by API version.
With this proposal, it is no longer necessary to add a prefix('api') when using Route::version()—the versioning syntax will handle the prefix automatically.

Route::version('v1', function () {
    Route::get('users', [V1\UserController::class, 'index']);
});
Route::version('v2', function () {
    Route::get('users', [V2\UserController::class, 'index']);
});

Forget about Route Version Detection that is personal preference.

Route List Output (php artisan route:list)

- GET /api/v1/users — **Deprecated:** Use `/api/v2/users` instead.
- GET /api/v2/users