FAQ
I'm wondering if anyone has provided both a REST-like API and a SOAP API to
their application and can provide some feedback from their experience.

I have an existing set of controllers that initially handled AJAX requests.
The controllers use a common base class that provides REST-like actions.
By creating a controller subclass, say App::Controller::Foo, I get actions
GET, POST, PUT, DELETE for /foo. The base class knows how to work with DBIC
for the Foo Result class and also by default looks for a form
App::Form::Foo. Kind of an auto-crud setup. What data (mostly columns) is
returned for GET is defined by configuration. The code that ends up in the
Foo controller is mostly access control (often by adding to the DBIC
resultset) the base class builds.

What eventually ends up happening is search, create, update, and delete get
called on a resultset.

These controllers essentially provide a useful API into the application as
well as supporting AJAX requests. I now need to add a SOAP API that will
provided the same functionality as the existing REST-like API.

I'm using Catalyst::Controller::SOAP and that gives me a Perl data structure
that represents the SOAP payload. Since I already have the REST actions I'm
wondering if it makes sense to simply flatten the SOAP request and
re-dispatch to the REST actions and make use of the existing logic in these
controllers.

Is anyone doing something like this? That is, remapping a SOAP request to
REST actions? Would I be better off writing a separate set of
self-contained SOAP controllers?

Also, does anyone have a suggestion how to version an API? That is, say I
have an API method POST /foo to create a new Foo object. Would it be better
to use something like POST /api/rest/version_2/foo?

--
Bill Moseley
moseley@hank.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.scsys.co.uk/pipermail/catalyst/attachments/20110406/ff6e67b8/attachment.htm

Search Discussions

  • Peter Edwards at Apr 6, 2011 at 2:13 pm

    On 6 April 2011 14:59, Bill Moseley wrote:

    I'm wondering if anyone has provided both a REST-like API and a SOAP API to
    their application and can provide some feedback from their experience.
    Hi Bill, we had to do the reverse of that (for a Perl app that wasn't using
    Catalyst) and added a REST API on to a SOAP one.
    I think a direct mapping of SOAP actions -> REST methods is your safest bet
    for keeping it intelligible and maintainable.
    SOAP is a four letter word, of course :-]

    Also, does anyone have a suggestion how to version an API? That is, say I
    have an API method POST /foo to create a new Foo object. Would it be better
    to use something like POST /api/rest/version_2/foo?
    Yes I've used the /api/v1/foo /api/v2/foo approach before and it works well
    and makes it easy to separate out old APIs for regression testing when you
    add new stuff.

    Regards, Peter
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: http://lists.scsys.co.uk/pipermail/catalyst/attachments/20110406/a0d00903/attachment.htm
  • Trevor Leffler at Apr 6, 2011 at 4:44 pm

    Peter Edwards wrote:
    On 6 April 2011 14:59, Bill Moseley wrote:

    Also, does anyone have a suggestion how to version an API? That is,
    say I have an API method POST /foo to create a new Foo object.
    Would it be better to use something like POST /api/rest/version_2/foo?


    Yes I've used the /api/v1/foo /api/v2/foo approach before and it works
    well and makes it easy to separate out old APIs for regression testing
    when you add new stuff.

    Regards, Peter
    Hi, I've also seen the use of HTTP request headers for specifying
    service API minor versions (and other bits). In particular, EBay comes
    to mind; they use v1, v2 in the end-point plus an
    X-EBAY-SOA-SERVICE-VERSION header.

    http://developer.ebay.com/DevZone/finding/Concepts/MakingACall.html#callstruct

    --Trevor
  • Bill Moseley at Apr 6, 2011 at 8:20 pm

    On Wed, Apr 6, 2011 at 9:44 AM, Trevor Leffler wrote:
    Hi, I've also seen the use of HTTP request headers for specifying service
    API minor versions (and other bits). In particular, EBay comes to mind;
    they use v1, v2 in the end-point plus an X-EBAY-SOA-SERVICE-VERSION header.
    I thought about doing that. Not sure where I'd hook in to the Catalyst
    request -- I guess before prepare_action modify the path to insert the
    version so that the correct version of controllers are used.

    That approach might also make it easier to fall back -- if no v2 controller
    exists then fallback to a previous version. That way only need to create
    new controllers for the methods that actually changed. Hopefully, we are
    not making new versions very often.



    On a side note, we came across this issue with Firefox and X- headers over
    the last few weeks:

    https://bugzilla.mozilla.org/show_bug.cgi?id=646378

    A customer was complaining of seemingly random failures and by logging
    request headers we could see that the requests that failed were missing all
    the X- headers. And for these requests the X- headers was necessary. (The
    load balancer was depending on the header to route the request to the
    correct web server.)


    --
    Bill Moseley
    moseley@hank.org
    -------------- next part --------------
    An HTML attachment was scrubbed...
    URL: http://lists.scsys.co.uk/pipermail/catalyst/attachments/20110406/27c21949/attachment.htm
  • Aristotle Pagaltzis at Apr 7, 2011 at 1:25 am

    * Trevor Leffler [2011-04-06 18:50]:
    Hi, I've also seen the use of HTTP request headers for
    specifying service API minor versions (and other bits). In
    particular, EBay comes to mind; they use v1, v2 in the
    end-point plus an X-EBAY-SOA-SERVICE-VERSION header.

    http://developer.ebay.com/DevZone/finding/Concepts/MakingACall.html#callstruct
    This is a very bad idea. No matter what problem you have,
    a custom HTTP header is very nearly certainly the wrong solution.
    For API versioning it definitely is.

    Putting the version in the URI is the right approach ? if in fact
    you even need an explicit version. (You can always switch to
    a different URI space no matter whether you made a provision for
    it using a version number in the URI or not.)

    Of course eBay didn?t have a lot of options, being that their API
    is SOAP-centric (even though they now support non-SOAP options).
    So don?t make their mistake: don?t use SOAP. If you inescapably
    have to support it as an option, then at least don?t design your
    API from its point of view.

    Regards,
    --
    Aristotle Pagaltzis // <http://plasmasturm.org/>
  • Dave Rolsky at Apr 7, 2011 at 3:16 am

    On Thu, 7 Apr 2011, Aristotle Pagaltzis wrote:

    This is a very bad idea. No matter what problem you have,
    a custom HTTP header is very nearly certainly the wrong solution.
    For API versioning it definitely is.
    My understanding of REST, at least, is that versioning should be done by
    specifying different Accept and Content-Type headers, like
    x-application/x-myapp-auction-item-v1.

    This makes sense with REST, since the URI for a thing should always stay
    the same, but it's representation can vary. The API version is part of
    that representation.


    -dave

    /*============================================================
    http://VegGuide.org http://blog.urth.org
    Your guide to all that's veg House Absolute(ly Pointless)
    ============================================================*/
  • Aristotle Pagaltzis at Apr 7, 2011 at 3:52 am

    * Dave Rolsky [2011-04-07 05:25]:
    On Thu, 7 Apr 2011, Aristotle Pagaltzis wrote:
    This is a very bad idea. No matter what problem you have,
    a custom HTTP header is very nearly certainly the wrong
    solution. For API versioning it definitely is.
    My understanding of REST, at least, is that versioning should
    be done by specifying different Accept and Content-Type
    headers, like x-application/x-myapp-auction-item-v1.

    This makes sense with REST, since the URI for a thing should
    always stay the same, but it's representation can vary. The API
    version is part of that representation.
    There isn?t any requirement in REST that a resource have only one
    URI. There is much less so any requirement that a resource be the
    equivalent of a platonic idea. In fact, if you try to treat them
    that way, you cause yourself problems that REST is meant to
    eliminate ? it increases the coupling of client and server that
    REST aims to loosen.

    Switching media types is not a bad idea, much better than using
    a header anyway. But you want to be very careful about just when
    you make a change as disruptive as that, as well you don?t want
    to use too application-specific media types, because doing so
    very nearly eliminates the opportunity to bind services together
    in unforeplanned ways (?serendipity?, in Roy?s words, ?mash-ups?
    if you are Web 2.0 hipster, ?synergy? if you are the CTO, or just
    plain ?integration? if you?re the one getting work done :-) ).

    Regards,
    --
    Aristotle Pagaltzis // <http://plasmasturm.org/>

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupcatalyst @
categoriescatalyst, perl
postedApr 6, '11 at 1:59p
activeApr 7, '11 at 3:52a
posts7
users5
websitecatalystframework.org
irc#catalyst

People

Translate

site design / logo © 2022 Grokbase