Developed with love by KnpLabs Hire us for your project!
20

ApiVersioningBundle

by XuruDragon

This bundle provide you a way to handle multiple version of your api. See `Usage` section to know how use this bundle

ApiVersioningBundle

Informations

Build Status - master

This bundle provide you a way to handle multiple version of your api.
See Usage section to know how ise this bundle

Installation

Step 1: Download the Bundle

Open a command console, enter your project directory and execute the
following command to download the latest stable version of this bundle:

$ composer require xurudragon/api-versioning-bundle

This command requires you to have Composer installed globally, as explained
in the installation chapter
of the Composer documentation.

Step 2: Enable the Bundle

Then, enable the bundle by adding it to the list of registered bundles
If you are on Symfony 3.* look in the app/AppKernel.php file of your project:

<?php
// app/AppKernel.php

// ...
class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new XuruDragon\ApiVersioningBundle\XuruDragonApiVersioningBundle(),
        );

        // ...
    }

    // ...
}

If you are on Symfony 4.* look in the config/bundles.php file of your project:

<?php

//config/bundles.php

return [
    // ....
    XuruDragon\ApiVersioningBundle\XuruDragonApiVersioningBundle::class => ['all' => true],
];

Step 3: Configuration

Nothing special to do here. Unless you want to change the header name sent to the api to processing versioning changes
You can add theses entries into your config files :

xurudragon_versioning:
    # Header name that should be sent to the api to processing versioning changes
    header_name: X-Accept-Version #Header name

Usage

Introduction

Your API reponse must always match the latest version of your API.

To support multiple versions, you must for each version of your API that breaks the backward compatibility:
1. create a change class inheriting from the following abstract class: XuruDragon\ApiVersioningBundle\Changes\AbstractChanges
2. add an entry in the configuration file corresponding to the class created previously

we recommend to you the following structure:
1. Create a folder named ApiChanges
2. Name your classes ApiChangesXYZ, with X for the Major version, Y for the Minor version and Z for the Patch version

We assume that you know the semantic versioning system

Create the Change Class

Here is the 0.9.0 class version, which assumes that your API version is at least 0.9.1 .

<?php
// ../ApiChanges/ApiChanges090.php

namespace Your\Bundle\ApiChanges;

use XuruDragon\ApiVersioningBundle\Changes\AbstractChanges,

class ApiChanges090 extends AbstractChanges
{

    /**
     * Apply version changes for current request.
     *
     * @param array $data
     *
     * @return null|array
     */
    public function apply(array $data = [])
    {
        return $data;
    }

    /**
     * Returns true if this version changes is supported for current request.
     *
     * @param array $data
     *
     * @return null|bool
     */
    public function supports(array $data = [])
    {
        return true;
    }
    // ...
}

You should now implement the apply and supports methods with your own logic.

supports should return true or false following if this version change support the actual data returned by your latest api version.

apply should do whatever you want to transform the actual data into an version that correspond to this api version. The returned array would be encoded in json and return to the api client that have make the request.

Example

Imagine that version 1.0.0 of your API adds an entry to the json output of one of the called services.
This entry would be "location" within the following data array returned by your latest API version :

$data = [
    'results' => [
        'firstname' => 'John',
        'lastname' => 'Doe',
        'location' => '4, Privet Drive, Little Whinging, Surey', 
    ],
];

You must then delete this data entry so that the requested version 0.9.0 matches what the calling client is waiting for.

You can do that by modifying the previously created class with the following code :

<?php
// ../ApiChanges/ApiChanges090.php

namespace Your\Bundle\ApiChanges;

use XuruDragon\ApiVersioningBundle\Changes\AbstractChanges,

/**
 * Class ApiChanges090.
 */
class ApiChanges090 extends AbstractChanges
{
    /**
     * {@inheritdoc}
     */
    public function apply(array $data = [])
    {
        //short example, but can be more more complex
        unset($data['results']['location']);

        return $data;
    }

    /**
     * {@inheritdoc}
     */
    public function supports(array $data = [])
    {
        //check for the entry column "location" in the results sub-array of $data
        return isset($data['results']) && array_search('location', array_keys($data['results']), true);
    }
    // ...
}

Of course here it's a pretty simple example of delete One entry, the processing could be more more complicated.

Register your version changes class in the configuration

    # Array of version changes that breaks backward compatibility
    # The array should be `desc` ordered.
    # The newest version should be the first and the oldest the last one
    versions:
        # version 0.9.0
        - { version_number: "0.9.0", changes_class: "Your\Bundle\ApiChanges\ApiChanges090"}

Here you are, no more configuration is required.

Copyright (c) 2018-* XuruDragon

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is furnished
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
xurudragon_versioning:

# Header name that should be sent to the api to processing versioning changes
header_name: X-Accept-Version

# Array of version changes that breaks backward compatibility
The array should be `desc` ordered.
The newest version should be the first and the oldest the last one
versions:
version_number: 0.0.1 # Required
changes_class: XuruDragon\VersioningBundle\Changes\Changes001 # Required
  • Change dependance from symfony/symfony to symfony/http-foundation
    By XuruDragon, 26 days ago
  • update readme to add travisci build info
    By web-flow, 26 days ago
  • Add travis configuration + readme + LICENSE
    By XuruDragon, 26 days ago
  • Set theme jekyll-theme-cayman
    By XuruDragon, 26 days ago
  • Changes to work with travisCI
    By XuruDragon, 26 days ago
  • Add phpunit test + cs fixer + some changes to namespace
    By XuruDragon, 26 days ago
  • Create README.md
    By web-flow, 27 days ago
  • init
    By XuruDragon, 27 days ago
  • Add composer file
    By XuruDragon, 27 days ago