README

Introduction

timopaul/laravel-api-versioning is a Laravel package that allows you to handle API versioning seamlessly by passing the version as a header parameter. It simplifies the process of managing multiple API versions while maintaining clean and structured code.

Features

Accepts API version via a custom header parameter.
Easy integration with existing Laravel applications.
Customizable versioning behavior through configuration.
Middleware for handling API version validation.

Installation

You can install the package via Composer:

composer require timopaul/laravel-api-versioning

Configuration

After installation, you can publish the configuration file to customize the package behavior:

php artisan vendor:publish --tag="api-versioning-config"

This will create a configuration file located at config/api-versioning.php. You can modify this file according to your requirements.

The default configuration file looks like this:

declare(strict_types=1);

return [
    /*
    |--------------------------------------------------------------------------
    | API Version Header Key
    |--------------------------------------------------------------------------
    |
    | The HTTP header that contains the API version. This value is used in the
    | middleware to determine the requested version.
    |
    */
    'header_key' => 'X-API-Version',

    /*
    |--------------------------------------------------------------------------
    | Default API Version
    |--------------------------------------------------------------------------
    |
    | If no API version is specified (e.g. for internal requests), this value
    | can be used as the default version. If `null` is specified here, the API
    | version is a required header parameter for every request.
    |
    */
    'default_version' => '1.0',

    /*
    |--------------------------------------------------------------------------
    | Default API Versions Enumeration
    |--------------------------------------------------------------------------
    |
    | Enumeration to define all possible versions of the API with identifier
    | and name.
    |
    */
    'enumeration_class' => \TimoPaul\LaravelApiVersioning\Enums\ApiVersion::class,

];

Managing Versions with Enums

The package uses an enumeration to define and manage API versions. This approach ensures consistency and type safety throughout your application. The ApiVersion enum is structured as follows:

declare(strict_types=1);

namespace TimoPaul\LaravelApiVersioning\Enums;

use TimoPaul\LaravelApiVersioning\Interfaces\ApiVersionInterface;
use TimoPaul\LaravelApiVersioning\Traits\ApiVersionEnumerationHelpers;

enum ApiVersion: string implements ApiVersionInterface
{
    use ApiVersionEnumerationHelpers;

    case v100 = '1.0.0';
    case v101 = '1.0.1';
    case v123 = '1.2.3';
    case v200b = '2.0.0 BETA';
}

Using this enum, you can easily reference specific API versions without hardcoding strings. For example, when defining routes or applying middleware:

use Timopaul\LaravelApiVersioning\Enums\ApiVersion;
use Illuminate\Support\Facades\Route;

Route::middleware(['api', 'api.version:' . ApiVersion::V1->value])->group(function () {
    Route::get('/example', [ExampleController::class, 'index']);
});

This centralized version management improves code maintainability and reduces errors.

Usage

Middleware

The package provides a middleware to handle API versioning. To enable it, add it to your route or global middleware stack:

// In routes/api.php
use Illuminate\Support\Facades\Route;

Route::middleware(['api-versioning'])->group(function () {
    Route::get('/example', [ExampleController::class, 'index']);
});

Accessing the API Version

You can access the requested API version in your controller or service using:

$version = app('api-version');

This will return the version passed in the API-Version header or the default version if none was provided.

Example Request

curl -X GET \
  -H "API-Version: v2" \
  https://your-api-domain.com/example

Testing

Run the package tests to ensure everything works as expected:

composer test

Contributing

Contributions are welcome! Please follow these steps:

Fork the repository from GitLab.
Create a new branch for your feature or bugfix.
Submit a pull request with a detailed description of your changes.

License

This package is open-sourced software licensed under the MIT License.

For more information, visit the GitLab repository.

timopaul / laravel-api-versioning

Maintainers

Details