[Catalyst] API Versioning for Web Services

Bill Moseley moseley at hank.org
Fri Jul 25 15:09:58 BST 2008

I'm looking for suggestions how to best support multiple API versions
in an application.

The API and web share many controller actions.  As is not uncommon,
actions available for the API are defined with an attribute:

    sub foo : Local XMLRPC( 'foo.get' ) {

This is great for sharing code as often the API just exposes
the same functionality as the web interface.

When a new version of the web application is released then all web
users see the new version at the same time.  If an action in the new
version expects an additional new parameter then the form posting to
that action is modified at the same time.

But, the API access to an application typically needs to be backward
compatible to allow API users time to update their client applications
with the newer requirements.

So, it seems I would need multiple controller actions that are
dispatched based on some version.

Here's one idea I was kicking around:

Say I have an existing controller action that is used by the web
users, but also available as an XMLRPC API method:

    sub widget : Local XMLRPC( 'widget.get' ) {

So in a new application version that controller action is changed
and now requires a new parameter and returns new data.

In the new version I want to support the new action but remain
backward compatible.

    # fetch widget for web and API
    sub widget : Local XMLRPC( 'widget.get' ) Version( 2 ) {

    # deprecated to support old version of API
    sub widget_old : XMLRPC( 'widget.get' ) Version( 1 ) {

Then in my custom API dispatcher match method I take the version into
consideration when matching actions.

Any better suggestions?

Bill Moseley
moseley at hank.org
Sent from my iMutt

More information about the Catalyst mailing list