If you introduce changes to your current API, your users might not upgrade their applications right away, so versioning is important to prevent existing applications to break when such changes are made.
There are several ways, none is standard:
- Use an uri parameter
/v1/users
- Use a query parameter
/users?version=v1
- Use a custom mime-type with an
Accept
headerAccept: application/json; version=1.0
- Use a custom header
X-Accept-Version: v1
The FOSRestBundle
allows you to use several of them at the same time or to choose one of them.
If you want to version your api with the uri, you can simply use the symfony router:
# config/routes.yaml
my_route:
# ...
path: /{version}/foo/route
Note: this will override the version
attribute of the request if you use the FOSRestBundle
versioning.
You should activate the versioning:
fos_rest:
versioning: true
If you do not want to allow all the methods described above, you should choose which version resolver to enable:
fos_rest:
versioning:
enabled: true
resolvers:
query: true # Query parameter: /users?version=v1
custom_header: true # X-Accept-Version header
media_type: # Accept header
enabled: true
regex: '/(v|version)=(?P<version>[0-9\.]+)/'
You can also choose the guessing order:
fos_rest:
versioning:
enabled: true
guessing_order:
- query
- custom_header
- media_type
The matched version is set as a Request attribute with the name version
, and when using JMS serializer it is also set as an exclusion strategy automatically in the ViewHandler
.
If you want to version by Accept header, you will need to do the following:
The format listener must be enabled
See
Format Listener <format_listener>
The client must pass the requested version in his header like this :
Accept:application/json;version=1.0
You must configure the possible mime types for all supported versions:
fos_rest: view: mime_types: json: ['application/json', 'application/json;version=1.0', 'application/json;version=1.1']
Note: If you have to handle huge versions and mime types, you can simplify the configuration with a php script:
// app/config/fos_rest_mime_types.php $versions = array( '1.0', '1.1', '2.0', ); $mimeTypes = array( 'json' => array( 'application/json', ), 'yml' => array( 'application/yaml', 'text/yaml', ), ); array_walk($mimeTypes, function (&$mimeTypes, $format, $versions) { $versionMimeTypes = array(); foreach ($mimeTypes as $mimeType) { foreach ($versions as $version) { array_push($versionMimeTypes, sprintf('%s;version=%s', $mimeType, $version)); array_push($versionMimeTypes, sprintf('%s;v=%s', $mimeType, $version)); } } $mimeTypes = array_merge($mimeTypes, $versionMimeTypes); }, $versions); $container->loadFromExtension('fos_rest', array( 'view' => array( 'mime_types' => $mimeTypes, ), ));
And then, import it from your Symfony config:
imports: - { resource: fos_rest_mime_types.php }
You should have tagged your entities with version information (@Since, @Until ...)
See this JMS Serializer article for details about versioning objects.
That's it, it should work now.
You can use conditions on your request to check for the version that was determined:
my_route:
# ...
condition: "request.attributes.get('version') == 'v2'"