[Catalyst] API Versioning for Web Services

[Markus Holzer]

Bill Moseley schrieb:
> 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?
>
>
>
>   

You could make the version of the api being used a parameter of the 
request, falling back to the latest stable version if not present. Then, 
in your controller you use a simple dispatch table to call the function 
that should the lifting.