[Catalyst] API Versioning for Web Services

[Wade.Stuart at fallon.com]

Bill Moseley <moseley at hank.org> wrote on 07/27/2008 11:09:46 AM:

> On Sat, Jul 26, 2008 at 06:00:39AM +0100, Matt S Trout wrote:
> >
> > sub widget :Local VersionedXMLRPC('widget.get') {
> >
> > sub widget_xmlrpc_v1 {
> >
> > have VersionedXMLRPC apply a custom a ction class that does ->can
> > based dispatch, same way Catalyst::Action::REST does.
>
> C::Action::REST uses "ActionClass('REST')" to specify the class for
> the action.  And with a custom request class, has a custom dispatcher to
> dispatch based on the request method.
>
> Your example above does not use ActionClass.  Were you suggesting that
> these XMLRPC actions have their own action class, and if so how would
> the actions be setup then?
>
> I would think the Catalyst approach would be something like this:
>
>     sub widget : Local ActionClass('XMLRPC', 'widget.get' ) {
>
>
> There's more than one approach, of course.
>
> My current approach (w/o versioning) is to have a custom dispatcher
> type (which I push onto $c->dispatcher->preload_dispatch_types).  I
> also have a custom HTTP::Body type to parse the XMLRPC payload.  Once
> the XMLRPC method name is known from the request the dispatcher
> searches for the matching action.
>
> But, I do like the approach of matching the action, and then using
> $controller->can to try and find an appropriate version as you
> suggested.
>
> By the way, my assumption is I would have the entire XMLRPC API
> versioned.  I asked about this on the XMLRPC list and it was
> recommended that instead I version individual methods.  That is, have
> separate method names that include a version:
>
>     widget.1.get
>     widget.2.get
>     etc.
>
> which would make the Catalyst part very simple, but I'm not sure I
> like that idea of each method having a version in the method name.
>

Bill,

      Icky,  I think the API should be versioned -- not methods.  What if
the methods across versions are not compatible (widget1 output used with
foo2) versioning the api forces all methods to be used with their tested
and versioned partners.  When you have 30 or 40 different revisions and
developers start relying on mismatching methods from different versions
that seems like a headache waiting to happen.

-Wade

-Wade