0.0.5 2017-09-05 16:55 UTC

This package is auto-updated.

Last update: 2024-03-28 00:27:03 UTC


Latest Version on Packagist Build Status StyleCI

This package is based on the API versioning scheme used at Stripe. Users pass a version header and you automatically migrate the request & response data to match the current version of your code.


You can update your API without worrying of users applications breaking with API Migrations.

You write these incrementing migrations to convert your request/responses go back in time to allow your users applications to work flawlessly.


  • User Version Pinning
  • Major API Versioning Supported
  • Convention Supplied with artisan commands

How to use in day to day development

You should create releases (including your current release) when releasing your API. This allows the system to know how to migrate a request/response to and older version of the API.

For example :

Current Release V1 - 2017-08-31 expects the response :

        'firstname' => 'Dwight',
        'lastname'  => 'Schrute',
        'title'     => 'Assistant to the Regional Manager'

Release V1 - 2017-08-01 expects the response :

        'firstname' => 'Dwight',
        'lastname'  => 'Schrute',
        'title'     => 'Assistant to the Regional Manager',
        'secret_title' => 'Assistant Regional Manager',

When your users are using the older API they expect to see that secret title.

It will then migrate the request 2017-08-31 to 2017-08-01.

While this is a simple example you can see the power with these migrations to create simple steps to migrate your current version of the api to an older version of the API very easily.


composer require lukepolo/laravel-api-migrations

Service Provider & Facade

This package supports Laravel 5.5 autoloading so the service provider and facade will be loaded automatically.

If you are using an earlier version of Laravel or have autoloading disabled you need to add the service provider and facade to config/app.php.

'providers' => [
'aliases' => [
    'LaravelApiMigrations' => \LukePOLO\LaravelApiMigrations\Facades\LaravelApiMigrations::class,


Add the middleware to your Http Kernel app/Http/Kernel.php.

You have a couple of choices where to put this, recommenced under the api middleware!

protected $middlewareGroups = [
    'api' => [


Run the following Artisan command to publish the package configuration to config/request-migrations.php.

php artisan vendor:publish --provider="LukePOLO\LaravelApiMigrations\ServiceProvider" --tag=config


Creating a Release

You can generate a new release using the Artisan CLI.

php artisan make:api-release

Creating a Migration

You can generate a new api migration using the Artisan CLI.

php artisan make:api-migration ExampleMigration

The command will generate a api migration and publish it to App/Http/ApiMigrations/V{VersionNumber}/Release_{YYYY_MM_DD}/{MigrationName}.

Caching Migrations

Once you move to prod you should cache the results

php artisan cache:api-migrations

Making HTTP Requests

By default when making a request to your API it will not run any migrations.

To use a different version of your api just attach a header :

    'Api-Version' : '2017-08-31'  

Writing the API migrations

migrateRequest method : This is used to convert your request to be valid to your most current route

migrateResponse method : This is used to convert your response to what you should expect for that version

Example : -- link to gist --


You should use the artisan commands above to create releases, including your current release. You can also set your current versions in the config.

You can tag your current versions in your config by setting it up like this :

    'current_versions' => [
        'V1' => '2017-01-31',

``### User Version Pinning With version pinning you can automatically keep users to that API and allow them to upgrade to your latest version at their convince. Once once your user hits your api for the first time it will set the most current version.

php artisan vendor:publish --provider="LukePOLO\LaravelApiMigrations\ServiceProvider" --tag=migrations

!!!! NOTE !!!!!

You must also make the column api_version fillable in your User model!


Please see CHANGELOG for more information what has changed recently.


composer test


Please see CONTRIBUTING for details.


If you discover any security related issues, please email instead of using the issue tracker.


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


This package was original idea build by Tom Schlick, but modified heavily.