Purpose
This library is useful when you want to version your Symfony-based REST API by relying on the Accept (for output) and Content-Type (for input) HTTP headers., (*1)
The library does all this by building on top of the powerful Symfony Serializer component., (*2)
For example: let's say in your application you ask for information about a user and you also specify the required Accept header:, (*3)
GET http://myapi.myapp.com/user/123
Accept: application/myapp;version=1;format=json
You get something like this:, (*4)
{
"user": {
"id": 123,
"name": "sobolan",
"email": "someemail@example.com",
"age": 99
}
}
However, let's say your mobile app only knows how to read/interpret XML content. Therefore, all you have to do is change the value of the format parameter:, (*5)
GET http://myapi.myapp.com/user/123
Accept: application/myapp;version=1;format=xml
Now you get something like this:, (*6)
<response>
<user>
<id>123</id>
<name>sobolan</name>
<email>someemail@example.com</email>
<age>99</age>
</user>
</response>
Same data, different format ;) . And, as you will see, it will require ZERO extra lines of code in your application., (*7)
Supporting different response structures at the same time
Let's say at some point you don't want this route to return the user-ID anymore, since it's a value that is internal to your system., (*8)
You could just remove it. But all your iOS/Android/desktop clients rely on it. If you remove it, these applications will break., (*9)
Instead, you could just use this library and have it support responses both with the user-ID and without. This is what the version parameter is for:, (*10)
GET http://myapi.myapp.com/user/123
Accept: application/myapp;version=1;format=json
Response:, (*11)
{
"user": {
"id": 123,
"name": "sobolan",
"email": "someemail@example.com",
"age": 99
}
}
If you use a different version, let's say "2", you can have the API do this:, (*12)
GET http://myapi.myapp.com/user/123
Accept: application/myapp;version=2;format=json
Response:, (*13)
{
"user": {
"name": "sobolan",
"email": "someemail@example.com",
"age": 99
}
}
Notice how the "id" field is missing. This is extremely easy to do with this library., (*14)
After you do this, all you have to do is gradually (and on your own time) migrate your clients to using version "2" of your API., (*15)
When you're done, just bump the default version of the API so that "id" doesn't show up by default and you're done !, (*16)
No more stressful syncing of deployments and no more nightmares of clients that might or might not break ;), (*17)
How to use it
A complete documentation about how to use the library can be found here: /doc/howtouse.md., (*18)
Please note that it may be trickier or more difficult to implement in the beginning. But it will feel more natural once you get used to it and its features., (*19)
Complete Example
A complete example that uses the library can be found here: sobolan/rest-negotiator-example., (*20)
License
This library is published under the MIT license., (*21)
Wallogit.com
