bbrothers/http-transitions

API versioning with transition stages (migrations) based on a request header.

v0.5.0 2019-04-15 15:56 UTC

Requires

• php: ^7.1
• ext-json: *
• illuminate/config: 5.5.*|5.6.*|5.7.*|5.8.*
• illuminate/contracts: 5.5.*|5.6.*|5.7.*|5.8.*
• illuminate/http: 5.5.*|5.6.*|5.7.*|5.8.*
• illuminate/support: 5.5.*|5.6.*|5.7.*|5.8.*

Requires (Dev)

• orchestra/testbench: ~3.7
• phpunit/phpunit: ^7.0
• squizlabs/php_codesniffer: ^2.3

MIT

• migrations
• http
• api
• schema
• middleware
• versioning
• transition

README

A package for transitioning HTTP requests and responses based on a version header.

Release updates to your API schema without breaking existing clients by creating Transition classes that transition the request and/or response to match the previously expected result. Each layer of transitions only needs to convert the current version to match the previous version, from there the request and response will be piped through the subsequent layers until they match the version requested in the Api-Version header.

Largely based on Stripe's API versioning article.

Install

$ composer require bbrothers/http-transitions

Middleware

In your app/Http/Kernel.php file, add:

protected $middleware = [
    Transitions\TransitionMiddleware::class
];

Service Provider

For Laravel 5.4, in your config/app.php file, in the providers array, add:

Transitions\TransitionProvider::class

Publish Config

php artisan vendor:publish --provider="Transitions\TransitionProvider"

Usage

Add version numbers and an array of Transition classes to the transitions.php file.

return [
   'headerKey' => 'Api-Version',
   'transitions'    => [
       '20160101' => [
           FullNameToNameTransition::class,
           NameToFirstNameLastNameTransition::class,
           BirthDateTransition::class,
       ],
       '20150101' => [
           FirstNameLastNameToFullNameTransition::class,
       ],
   ],
]

Create a transition:

class NameToFirstNameLastNameTransition extends Transition
{

    public function transformResponse(Response $response) : Response
    {
        $content = json_decode($response->getContent(), true);
        $content = array_diff_key(array_merge($content, $content['name']), ['name' => true]);

        return $response->setContent(json_encode($content));
    }
}

Transition Generators

$ php artisan make:transition NameToFirstNameLastNameTransition

Optionally, the --request-only or --response-only flags can be added to create a transform that only generates a transformRequest or transformResponse method respectively.

Change log

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

License

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