[WIP] added support for a API versioning #136

wants to merge 11 commits into


None yet

lsmith77 commented Oct 6, 2011

This PR will eventually fix #12 and #30

For now we will only support media type based versioning (aka no URL based versioning)
See also the following links for details:

basically it looks like the best approach will be to replace the default RouterListener by simply registering a request listener that loads before the default one. In this listener we will need to examine the accept headers to determine the format and based on this decide which controller to use.

Now the tricky bit is that essentially for a single pattern, we will need to have a list of potential controllers we should examine. I have not yet found a good way to do this. Atm I would be inclined to say the best solution would be to support multiple resources per route:

There are also some things still missing (on all inclusive list):

Also note that through out all of this we must be aware that some browsers seem to prefer XHTML or worse XML over HTML:


stof commented Dec 18, 2011

@lsmith77 any news here ?


lsmith77 commented Dec 18, 2011

no .. basically the notes in the PR description are still valid, but its a fair bit of work and i haven't been able to work on it further ..


everzet commented Dec 30, 2011

Needs to be updated to support new Routing architecture. But it should be fairly easy as new arch is freaking clean :-D


cystbear commented Mar 22, 2012

@lsmith77 will you add object versioning from JMSSerializerBundle doc link ?


lsmith77 commented Mar 22, 2012

this PR is currently idling unfortunately. but yes thats the idea and we should support this right now already. aka allow setting the serializer version via the View class.


On 22.03.2012, at 10:43, Oleg Zinchenko reply@reply.github.com wrote:

@lsmith77 will you add object versioning from JMSSerializerBundle doc link ?

Reply to this email directly or view it on GitHub:
#136 (comment)


adrienbrault commented Jun 9, 2012

Hi, any news on this ? (maybe after yesterday's REST talk at symfony live ?)
What needs to be done ?


lsmith77 commented Jun 11, 2012

no .. there is no progress here aside from some general improvements to better integrate JMSSerializerBundle inside the View class. that BadFaith lib is however slowly, but surely, maturing.


breerly commented Jun 25, 2012

Any way I can help scoot this along? What's the block exactly?


lsmith77 commented Jun 26, 2012

the key thing is improving the support fir mime types inside the routing. this is the basis for mime type based versioning. see the link to the BadFaith lib. it seems like Flow3 1.1 will also feature a solution for Accept header negotiation which could serve as an inspiration.


breerly commented Jun 26, 2012

Any chance we could look at URI versioning for the time being since that will likely be desired by many users?


lsmith77 commented Jun 26, 2012

personally i am not too interested to work on that. also i dont think doing url based versioning is so hard to do right now already since for that mainly all you need is url pattern based routing which already exists and then you just point to different controllers leveraging inheritance where needed.


lsmith77 commented Jul 13, 2012

here is what the flow3 guys did for routing with content type negotiation:


lsmith77 commented Oct 24, 2012


gimler commented Apr 18, 2013

any news


lsmith77 commented Apr 18, 2013

nope. symfony/symfony#5711 is stalled which seemed like the most promising initiative for a while.


blaugueux commented May 6, 2013

The version need to be also configured in the SerializationContext object.

API versioning still out in the cold?


lsmith77 commented Aug 7, 2013

yes .. there is some progress in terms of a better content negotiation lib with https://github.com/willdurand/Negotiation but now the big task is left of integrating it within the Routing system

/cc @willdurand


willdurand commented Aug 7, 2013

Yup. Don't really know how to that though.

I did API versioning once using different routes /v1/..., /v2/... but it is not "cool". What we want is to leverage the Accept header but then what? How do we organize controllers and actions?

  • A sub-namespace?
  • A specific controller name mapped to a version somewhere?
  • Something else?

I thought about using a proxy controller that would forward the request to the right controller.

Example: the routing uses Controller\UserController. In this controller, if the version is:

  • v1 then we use Controller\V1\UserController
  • v2 then we use Controller\V2\UserController

lsmith77 commented Aug 8, 2013

we could maybe do a simple solution that will likely work in more than 80% of the cases. we could have a very early listener that looks at the media type and if it finds there is only one then we attempt to extract a version via a convention (optionally via some callback). this version is set as a request attribute and can therefore be checked via a route requirement.


willdurand commented Aug 8, 2013

Ah I am stupid. Yes, using the routing layer makes sense.

Actually @meandmymonkey and I thought about a similar approach lately using a listener which does negotiation before the routing using https://github.com/willdurand/Negotiation and setting request attributes.


lsmith77 commented Aug 8, 2013

anyone want to try and implement it? :)


willdurand commented Aug 14, 2013

It does not work. UrlMatcher don't use attributes.. I think we need a RequestMatcher, but don't know who to inject it into the RouterListener...


lsmith77 commented Aug 14, 2013

what about using the default then?


willdurand commented Aug 14, 2013

See this: willdurand/BazingaRestExtraBundle@5880f3e

Which default?

So, the UrlMatcher is not able to check attributes other than _method and _scheme. It is not able to check "custom" attributes. That is why we need a RequestMatcher but it is not injected by default in the RouterListener, and I am not sure to know how to do that the right way.


lsmith77 commented Aug 15, 2013

i was thinking the route defaults .. but they obviously don't exist yet .. so nevermind.
btw .. do you really think it makes sense to add this feature to that Bundle rather than adding it here?

@Tobion .. maybe you can help here?


willdurand commented Aug 15, 2013

do you really think it makes sense to add this feature to that Bundle rather than adding it here?

Not at all! I just hacked into this bundle as it does not pollute that one, and it made things easier in my test project. This feature MUST be part of the FOSRestBundle.

So now that we know that this solution does not work, we need to find a new idea :p

kbond commented Aug 15, 2013

Should 2 different versions go to 2 different controllers?

Shouldn't they both go to the same controller that has something like this:

$serializer->serialize($object, 'json', SerializationContext::create()->setVersion($versionFromAcceptHeader));



willdurand commented Aug 16, 2013

@kbond you could do more stuff than changing the "view" of your data between two given versions.

@kbond https://github.com/kbond Absolutely... two different versions of
an API could do very different things, despite identical endpoints.

On Fri, Aug 16, 2013 at 11:43 AM, William Durand

@kbond https://github.com/kbond you could do more stuff than changing
the "view" of your data between two given versions.

Reply to this email directly or view it on GitHubhttps://github.com/FriendsOfSymfony/FOSRestBundle/pull/136#issuecomment-22743064

Claymm commented Feb 5, 2014

Is there anything stable already released about a dynamic versioning support with FosRestBundle and JMSSerializer (for Until and Since annotation support)?

lsmith77 closed this Oct 20, 2014

lsmith77 referenced this pull request Oct 20, 2014


[META] API versioning #890

GuilhemN deleted the api_versioning branch Mar 17, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment