Migrations for your API
Open Issues: 0
- php: ^7.0
- illuminate/config: 5.4.*|5.5.*
- illuminate/contracts: 5.4.*|5.5.*
- illuminate/http: 5.4.*|5.5.*
- illuminate/support: 5.4.*|5.5.*
- orchestra/testbench: ~3.4
- phpunit/phpunit: ^6.0
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
'providers' => [ ... \LukePOLO\LaravelApiMigrations\ServiceProvider::class, ]
'aliases' => [ ... 'LaravelApiMigrations' => \LukePOLO\LaravelApiMigrations\Facades\LaravelApiMigrations::class, ]
Add the middleware to your Http Kernel
You have a couple of choices where to put this, recommenced under the api middleware!
protected $middlewareGroups = [ 'api' => [ ... \LukePOLO\LaravelApiMigrations\LaravelApiMigrationsMiddleware::class, ]; ]
Run the following Artisan command to publish the package configuration to
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
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
Please see CHANGELOG for more information what has changed recently.
Please see CONTRIBUTING for details.
If you discover any security related issues, please email firstname.lastname@example.org 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.