ApiVersioningBundle
Informations
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.
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, 1 year ago
-
update readme to add travisci build info
By web-flow, 1 year ago
-
Add travis configuration + readme + LICENSE
By XuruDragon, 1 year ago
-
Set theme jekyll-theme-cayman
By XuruDragon, 1 year ago
-
Changes to work with travisCI
By XuruDragon, 1 year ago
-
Add phpunit test + cs fixer + some changes to namespace
By XuruDragon, 1 year ago
-
Create README.md
By web-flow, 1 year ago
-
init
By XuruDragon, 1 year ago
-
Add composer file
By XuruDragon, 1 year ago