Versioning Resources

[Matt Gersting]

Does anyone have a system for versioning Taffy resources that they really like?

I've got an API running that's providing data for native iOS and Android applications and I'm reworking how a given resource works.  We want non-updated applications to still function though, so the original resource must remain.  I have a simple /api/version/resource scheme going now, but it doesn't seem particularly elegant in the long run.  Curious what the community might be doing.

[Mark Drew]

Most services that are versioned tend to be something like:

http://domain.com/<version>/actions

So I guess this is the way that Taffy should work right?

Regards

Mark Drew

[Adam Tuttle]

I agree with Mark. Generally I just create a versioned API as a whole.

api.domain.com/v1/users/

api.domain.com/v2/users/

etc...

Then each v1, v2, etc folder is its own Taffy application.

I think trying to maintain different versions of each resource would be too confusing for the user. ("So I use v3 for /users but v1 for /schools ???")

Adam

[Matt Gersting]

Sorry - somehow I left that out of my initial comment. Yes, I'm currently using the format /1.0/resource for my versioning, and Taffy does support that even in a single application. What it seems to be leading towards though is a lot of similarly named CFCs doing very similar things.  I'm not a huge fan of the file clutter and the repetition of code.

Adam it sounds like your way around the file clutter is having each version be a separate Taffy app.  I may look into that route.  Just curious what folks are doing.  I'm suspicious there may be a clever conventions-based way to build in the versioning intra-app and also alleviate some of the file clutter and code repetition...it's just not crystallizing for me at the moment.

I suspect my brain will continue to churn a little :)

[Adam Tuttle]

Hmm...

One of the ER's on the board for next version is to support subfolders inside /resources. What do people think about using this to support versioning, somehow?

/resources/v1/users.cfc, etc.

Matt, if you have zero changes to a cfc, and you just need to keep it listed as part of v2 so that everything is up to the same version number, you could always do something like this:

component extends="resources.v1users" taffy_uri="/v2/users" {}

Then all of the functionality in the v1 cfc is inherited by your v2 cfc and all you've done is update its uri, and the old URI is still supported.

This does add to file clutter, but at least the code isn't repeated.

Adam

[Brian Panulla]

On 11/18/11 8:56 AM, Matt Gersting wrote:
> Sorry - somehow I left that out of my initial comment. Yes, I'm
> currently using the format /1.0/resource for my versioning, and Taffy
> does support that even in a single application. What it seems to be
> leading towards though is a lot of similarly named CFCs doing very
> similar things. I'm not a huge fan of the file clutter and the
> repetition of code.

I see this as more of a deployment problem. If you're versioning the
releases of your code with an SCM tool (Subversion, Git, whatever) you
can use the branches in your SCM to manage the versions of your API.
Assemble the code that gets deployed to your server from multiple
branches (v1, v2, etc)

http://api.mysite.com/1.0/ -> export of svn://myAPI/branches/1.0/
http://api.mysite.com/1.1/ -> export of svn://myAPI/branches/1.1/
http://api.mysite.com/bleedingedge/ -> checkout of svn://myAPI/trunk/

rather than have multiple versions of the API in your current main
development branch/trunk/head.

I think this is a much saner practice than having the framework try to
baby you into better code deployment management :) But then again I'm
sorta philosophically against having version numbers in my URIs in the
first place.

--
Brian Panulla
Principal
Brainpan Labs
(503) 40-NTLOG

[Adam Tuttle]

Smart.

Adam

[AJ Mercer]

another option is to use the media type

eg http://barelyenough.org/blog/2008/05/versioning-rest-web-services/

--

AJ Mercer
<webonix:net strength="Industrial" /> | <webonix:org community="Open" />
http://twitter.com/webonix

Railo Community Manager

[Matt Gersting]

The version numbers in the URI's are for the consumers, obviously.  It allows us to support multiple client versions in situations where we can't control it.  In our case, we can't force the users of our iPhone applications to upgrade to the latest version (well, we could break their copy by not supporting it in the API, but that seems like bad business) so we need a mechanism to allow legacy support.

There's definitely an elegance to your approach.  I like it better than anything I've been brainstorming, but depending on the specifics I could see a few issues coming up.

So, let me clarify - in your scheme, /1.0 and /1.1 are physical folders and inside of that you're not exporting endpoints you're exporting an entire Taffy application - such that each folder is a standalone Taffy instance?

[Matt Gersting]

AJ - very interesting read.  I'm definitely looking into this - thank you.

[Adam Tuttle]

>So, let me clarify - in your scheme, /1.0 and /1.1 are physical folders and 

>inside of that you're not exporting endpoints you're exporting an entire Taffy 

>application - such that each folder is a standalone Taffy instance?

Exactly.

Adam

On Mon, Nov 21, 2011 at 4:45 PM, Matt Gersting <mger...@gmail.com> wrote:

[Matt Gersting]

Cool - I believe that would actually take care of the one hiccup I thought there might be.
In my mind I was trying to share a Taffy instance, but I suppose at the end of the day that's not the end of the world.