Skip to content

[WIP] added support for a API versioning #136

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 11 commits into from
Closed

Conversation

lsmith77
Copy link
Member

@lsmith77 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:
http://www.informit.com/articles/article.aspx?p=1566460
http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

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:
symfony/symfony#2145

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:
http://www.gethifi.com/blog/browser-rest-http-accept-headers

@stof
Copy link
Member

stof commented Dec 18, 2011

@lsmith77 any news here ?

@lsmith77
Copy link
Member Author

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
Copy link
Contributor

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
Copy link
Member

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

@lsmith77
Copy link
Member Author

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.

regards,
Lukas

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)

@lsmith77
Copy link
Member Author

lsmith77 commented Apr 3, 2012

@adrienbrault
Copy link
Contributor

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

@lsmith77
Copy link
Member Author

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.

@HelloGrayson
Copy link

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

@lsmith77
Copy link
Member Author

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.

@HelloGrayson
Copy link

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

@lsmith77
Copy link
Member Author

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
Copy link
Member Author

here is what the flow3 guys did for routing with content type negotiation:
https://review.typo3.org/#/c/11683/1

@lsmith77
Copy link
Member Author

see also symfony/symfony#5711

@gimler
Copy link
Contributor

gimler commented Apr 18, 2013

any news

@lsmith77
Copy link
Member Author

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

@blaugueux
Copy link
Contributor

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

@Codepadawan
Copy link

API versioning still out in the cold?

@lsmith77
Copy link
Member Author

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
Copy link
Member

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
Copy link
Member Author

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
Copy link
Member

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

@denderello
Copy link

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
Copy link
Member Author

lsmith77 commented Aug 8, 2013

anyone want to try and implement it? :)

@willdurand
Copy link
Member

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
Copy link
Member Author

what about using the default then?

@willdurand
Copy link
Member

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
Copy link
Member Author

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
Copy link
Member

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
Copy link

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
Copy link
Member

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

@Codepadawan
Copy link

@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
notifications@github.comwrote:

@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//pull/136#issuecomment-22743064
.

@clemblanco
Copy link

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

@lsmith77 lsmith77 closed this Oct 20, 2014
@lsmith77 lsmith77 mentioned this pull request Oct 20, 2014
@GuilhemN GuilhemN deleted the api_versioning branch March 17, 2016 20:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

look at providing ways to handle API versioning