[Catalyst] General API question: REST + SOAP
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 mose...@hank.org ___ List: Catalyst@lists.scsys.co.uk Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/ Dev site: http://dev.catalyst.perl.org/
Re: [Catalyst] General API question: REST + SOAP
On 6 April 2011 14:59, Bill Moseley mose...@hank.org 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 ___ List: Catalyst@lists.scsys.co.uk Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/ Dev site: http://dev.catalyst.perl.org/
Re: [Catalyst] General API question: REST + SOAP
Peter Edwards wrote: On 6 April 2011 14:59, Bill Moseley mose...@hank.org mailto:mose...@hank.org 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 ___ List: Catalyst@lists.scsys.co.uk Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/ Dev site: http://dev.catalyst.perl.org/
Re: [Catalyst] General API question: REST + SOAP
On Wed, Apr 6, 2011 at 9:44 AM, Trevor Leffler tleff...@uw.edu 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 mose...@hank.org ___ List: Catalyst@lists.scsys.co.uk Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/ Dev site: http://dev.catalyst.perl.org/
[Catalyst] Re: General API question: REST + SOAP
* Trevor Leffler tleff...@uw.edu [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/ ___ List: Catalyst@lists.scsys.co.uk Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/ Dev site: http://dev.catalyst.perl.org/
Re: [Catalyst] Re: General API question: REST + SOAP
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) */ ___ List: Catalyst@lists.scsys.co.uk Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/ Dev site: http://dev.catalyst.perl.org/
[Catalyst] Re: General API question: REST + SOAP
* Dave Rolsky auta...@urth.org [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/ ___ List: Catalyst@lists.scsys.co.uk Listinfo: http://lists.scsys.co.uk/cgi-bin/mailman/listinfo/catalyst Searchable archive: http://www.mail-archive.com/catalyst@lists.scsys.co.uk/ Dev site: http://dev.catalyst.perl.org/
