API are like any other programmed systems : they evolve during time, either with bugfixes or feature addition. There is a roadmap that can eventually bring to a backward compatibility break to ensure proper evolution regarding new features.
Versionning is important, mainly to provide your API clients ways to ensure they use the proper version regarding their needs.
Few ways :
- Domain name :
- URI prefix :
- Query string :
- Custom HTTP header :
Accept HTTP header :
Accept: application/vendor.app.your-app+json; version=4.0.0
Keep as the rule of thumb than changing URLs are generally bad idea. HTTP headers are the way to go. Below is a configuration possibility for the
FOSRestBundle configuration for
2 keys to add to FOSRestBundle configuration :
You need to tell FOSRestBundle you are using versionning in your app :
fos_rest: ... versioning: enabled: true resolvers: media_type: # Accept header enabled: true regex: '/(v|version)=(?P<version>[0-9\.]+)/'
Of course, you an freely adapt the regex to your needs.
Add MIME type
As you can see above, the MIME type you send is now custom (
application/vendor.app.your-app+json; version=4.0.0). You need to tell FOSRestBundle to accept it :
fos_rest: ... view: ... mime_types: json: ['application/json', 'application/json;version=1.0', 'application/json;version=2.0']
For the sake of brevity, I just put the matching configurations key with