Package

Grazulex Laravel Apiroute

Complete API versioning lifecycle management for Laravel

Package

grazulex/laravel-apiroute

View on GitHub →

Laravel ApiRoute

Complete API versioning lifecycle management for Laravel

Features

  • Multi-strategy versioning - URI path, Header, Query parameter, or Accept header
  • Automatic deprecation headers - RFC 8594 (Deprecation) and RFC 7231 (Sunset) compliant
  • Version lifecycle management - Active, Deprecated, Sunset, Removed states
  • Intelligent fallback - Route fallback to previous versions when needed
  • Artisan commands - Scaffold, monitor, and manage API versions
  • Usage tracking - Optional analytics per API version
  • Zero configuration start - Works out of the box with sensible defaults

Requirements

  • PHP 8.3+
  • Laravel 12.x

Installation

composer require grazulex/laravel-apiroute

Publish the configuration file:

php artisan vendor:publish --tag="apiroute-config"

Quick Start

Define your API versions in routes/api.php:

use Grazulex\ApiRoute\Facades\ApiRoute;

// Version 1 - Deprecated, sunset planned
ApiRoute::version('v1', function () {
    Route::apiResource('users', App\Http\Controllers\Api\V1\UserController::class);
})
->deprecated('2025-06-01')
->sunset('2025-12-01');

// Version 2 - Current stable version
ApiRoute::version('v2', function () {
    Route::apiResource('users', App\Http\Controllers\Api\V2\UserController::class);
})->current();

// Version 3 - Beta/Preview
ApiRoute::version('v3', function () {
    Route::apiResource('users', App\Http\Controllers\Api\V3\UserController::class);
})->beta();

Versioning Strategies

URI Path (Default)

GET /api/v1/users
GET /api/v2/users

Header

GET /api/users
X-API-Version: 2

Query Parameter

GET /api/users?api_version=2

Accept Header

GET /api/users
Accept: application/vnd.api.v2+json

Automatic Headers

On deprecated versions, responses include RFC-compliant headers:

HTTP/1.1 200 OK
Deprecation: Sun, 01 Jun 2025 00:00:00 GMT
Sunset: Mon, 01 Dec 2025 00:00:00 GMT
Link: </api/v2/users>; rel="successor-version"
X-API-Version: v1
X-API-Version-Status: deprecated

Artisan Commands

# View status of all API versions
php artisan api:status

# Create a new API version
php artisan api:version v3 --copy-from=v2

# Mark a version as deprecated
php artisan api:deprecate v1 --on=2025-06-01 --sunset=2025-12-01

# View usage statistics
php artisan api:stats --period=30

Configuration

// config/apiroute.php

return [
    // Detection strategy: 'uri', 'header', 'query', 'accept'
    'strategy' => 'uri',

    // Default version when none specified
    'default_version' => 'latest',

    // Fallback behavior
    'fallback' => [
        'enabled' => true,
        'strategy' => 'previous',
    ],

    // Sunset behavior: 'reject', 'warn', 'allow'
    'sunset' => [
        'action' => 'reject',
        'status_code' => 410,
    ],

    // Response headers
    'headers' => [
        'enabled' => true,
        'include' => [
            'version' => true,
            'deprecation' => true,
            'sunset' => true,
        ],
    ],
];

Testing

composer test

Code Quality

# Run all quality checks
composer full

# Individual checks
composer test:lint   # Laravel Pint
composer test:types  # PHPStan
composer test:unit   # Pest

Changelog

Please see RELEASES for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

Grazulex Laravel Apiroute Related Articles

Laravel API Route image

Laravel API Route

Read article
Switch Between Personas in Laravel With the MultiPersona Package image

Switch Between Personas in Laravel With the MultiPersona Package

Read article
Record and Replay Requests With Laravel ChronoTrace image

Record and Replay Requests With Laravel ChronoTrace

Read article
Laravel Devtoolbox: Your Swiss Army Knife Artisan CLI image

Laravel Devtoolbox: Your Swiss Army Knife Artisan CLI

Read article
Generate Complete Application Modules with a Single Command using Laravel TurboMaker image

Generate Complete Application Modules with a Single Command using Laravel TurboMaker

Read article
Generate Secure Temporary Share Links for Files in Laravel image

Generate Secure Temporary Share Links for Files in Laravel

Read article

PhpStorm

The go-to PHP IDE with extensive out-of-the-box support for Laravel and its ecosystem.

PhpStorm

Let your users buy domains without leaving your app

If your Laravel app gives users a site, a storefront, or a workspace, they’ll eventually want their own domain. The name.com API lets them search, register, and connect one without leaving your product. It’s a clean REST API, so Laravel’s HTTP client is all you need.

Let your users buy domains without leaving your app

Acquaint Softtech

Acquaint Softtech offers AI-ready Laravel developers who onboard in 48 hours at $3000/Month with no lengthy sales process and a 100 percent money-back guarantee.

Acquaint Softtech

NativePHP

The fastest way to build fully native apps for any platform (with AI or not)

NativePHP

Kirschbaum

Providing innovation and stability to ensure your web application succeeds.

Kirschbaum

Harpoon: Next generation time tracking and invoicing

The next generation time-tracking and billing software that helps your agency plan and forecast a profitable future.

Harpoon: Next generation time tracking and invoicing