Re: API wrapper best practices?
Message: 4 Date: Mon, 25 Mar 2013 01:04:28 + From: Sam Kington s...@illuminated.co.uk Subject: Re: API wrapper best practices? To: London.pm Perl M\[ou\]ngers london.pm@london.pm.org Message-ID: 10d48713-d33c-40f3-84e9-b28c52d40...@illuminated.co.uk Content-Type: text/plain; charset=iso-8859-1 On 24 Mar 2013, at 13:13, Ashley Hindmarsh ash+p...@best-scarper.co.uk wrote: I guess the holy grail is something that takes the API schema and builds the classes on-the-fly, and is closer to what Dave Hodg is after. People thought of that, and now we have SOAP. So be careful for what you wish for. I was using SOAP::WSDL as it reached v2.0 (ca. 2007). It features a complete wrapping of XML Schema data types, from which a Perl wrapper (accessors etc) can be generated, although you have to live with that minimalism (e.g. all arrays + containers - no mappings). Just wonder if the XML Schema wrapping could be extracted for use with RESTful APIs which have well-defined schemas (I guess I may have just volunteered) Ash Sam -- Website: http://www.illuminated.co.uk/
Re: API wrapper best practices?
On 2013-03-26 Ashley Hindmarsh ash+p...@best-scarper.co.uk wrote: Just wonder if the XML Schema wrapping could be extracted Isn't that what XML::Compile does? -- Dakkar - Mobilis in mobile GPG public key fingerprint = A071 E618 DD2C 5901 9574 6FE2 40EA 9883 7519 3F88 key id = 0x75193F88 Nature commits no errors; right and wrong are human categories. -- PARDOT KYNES, Arrakis Lectures signature.asc Description: PGP signature
Re: API wrapper best practices?
* Ashley Hindmarsh (ash+p...@best-scarper.co.uk) [130326 12:26]: I was using SOAP::WSDL as it reached v2.0 (ca. 2007). Martin Kutter (maintainer of SOAP::Lite and SOAP::WSDL) told me that, in his opinion, the modules were on their end: SOAP message are often too complex nowadays. He does fix bugs, now and then. It features a complete wrapping of XML Schema data types, from which a Perl wrapper (accessors etc) can be generated, although you have to live with that minimalism (e.g. all arrays + containers - no mappings). Just wonder if the XML Schema wrapping could be extracted for use with RESTful APIs which have well-defined schemas (I guess I may have just volunteered) As Gianni correctly states: that is what XML::Compile(::SOAP) is doing. It has many users. -- Regards, MarkOv Mark Overmeer MScMARKOV Solutions m...@overmeer.net soluti...@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net
Re: API wrapper best practices?
On 26 March 2013 13:14, Mark Overmeer m...@overmeer.net wrote: * Ashley Hindmarsh (ash+p...@best-scarper.co.uk) [130326 12:26]: I was using SOAP::WSDL as it reached v2.0 (ca. 2007). Martin Kutter (maintainer of SOAP::Lite and SOAP::WSDL) told me that, in his opinion, the modules were on their end: SOAP message are often too complex nowadays. He does fix bugs, now and then. Thanks Mark. I was patching some bugs for Martin back then. SOAP interop is hell. It features a complete wrapping of XML Schema data types, from which a Perl wrapper (accessors etc) can be generated, although you have to live with that minimalism (e.g. all arrays + containers - no mappings). Just wonder if the XML Schema wrapping could be extracted for use with RESTful APIs which have well-defined schemas (I guess I may have just volunteered) As Gianni correctly states: that is what XML::Compile(::SOAP) is doing. It has many users. Gianni? I guess I'll see that on the next digest. thanks, Ash -- Regards, MarkOv Mark Overmeer MScMARKOV Solutions m...@overmeer.net soluti...@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net
Re: API wrapper best practices?
* Ashley Hindmarsh (a...@best-scarper.co.uk) [130326 15:24]: On 26 March 2013 13:14, Mark Overmeer m...@overmeer.net wrote: * Ashley Hindmarsh (ash+p...@best-scarper.co.uk) [130326 12:26]: I was using SOAP::WSDL as it reached v2.0 (ca. 2007). Martin Kutter (maintainer of SOAP::Lite and SOAP::WSDL) told me that, in his opinion, the modules were on their end: SOAP message are often too complex nowadays. He does fix bugs, now and then. Thanks Mark. I was patching some bugs for Martin back then. SOAP interop is hell. SOAP itself is a poor interface, but most of the hell is SOAP::Lite. I am only aware of one usage problem at the moment: Sharepoint servers report internal errors in a erroneous fault structure ;-) Some common schema bugs have simple work-arounds. Schema's are much harder than most programmers expect. That's why XML::Compile does the client-side validation. It is very hard to use SOAP::Lite correctly. -- Regards, MarkOv Mark Overmeer MScMARKOV Solutions m...@overmeer.net soluti...@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net
Re: API wrapper best practices?
On 23 March 2013 16:01, Dave Hodgkinson da...@hodgkinson.org wrote: So I'm writing an interface to an API. It's a simple info request one. What top tips do we have for writing one that doesn't suck? I'd just go for a new that takes the auth info, methods to go fetch the information and being lazy, just let the data be accessible through the selfish hash. I'm not going to create objects for all the data objects at this point nor accessors for the individual fields. Well, maybe a few key ones. Suggestions for anything better, lazier, more modern? This is one of the best API wrappers I've used in a while: https://npmjs.org/package/redis It's great because once I've read the connection docs I can then use it without having to refer back to its docs, and instead use the really good ones at http://redis.io/commands But it does throw is a couple of handy helpers where it is suitable - eg https://github.com/mranney/node_redis#friendlier-hash-commands So really simple to learn, lets me use the core docs easily and helps out a bit when appropriate :) Cheers, Edmund. PS note the super cute queuing of requests until the connection is made: https://github.com/mranney/node_redis#ready
Re: API wrapper best practices?
On Sat, Mar 23, 2013 at 04:01:43PM +, Dave Hodgkinson wrote:
So I'm writing an interface to an API. It's a simple info request one.
What top tips do we have for writing one that doesn't suck? I'd
just go for a new that takes the auth info, methods to go fetch
the information and being lazy, just let the data be accessible
through the selfish hash.
I'm not going to create objects for all the data objects at this point
nor accessors for the individual fields. Well, maybe a few key ones.
I don't like the way that some API modules have eleventy bajillion
objects which get in the damned way of the data. OTOH when I do want
objects, I *really* want them.
Suggestions for anything better, lazier, more modern?
If you're clever you can auto-generate your objects on the fly. Don't
forget, an object is nothing more than a blessed scalar. It doesn't
really need a module.
All you need to do is to bless things into a namespace and arrange for
that namespace to inherit some methods:
my $object = bless($hash, 'Foo::Bar::Baz');
@Foo::Bar::Baz::ISA = ('Foo::Base');
That can give you the best of both worlds, with minimal coding - you
just need to write the base class - and if you later find that some of
your classes need to be a bit more full-fat, it's easy to implement
them while still using classes generated on the fly for everything else.
--
David Cantrell | Official London Perl Mongers Bad Influence
All principles of gravity are negated by fear
-- Cartoon Law V
Re: API wrapper best practices?
On 25 Mar 2013, at 15:23, David Cantrell wrote: I don't like the way that some API modules have eleventy bajillion objects which get in the damned way of the data. OTOH when I do want objects, I *really* want them. I once worked with a company who worked with another company who had brought in IBM. And nobody had told the nice people at IBM that they wanted a CORBA interface to upload live content, you know trivial little bits of content, like oh say for example horse racing results . not important at all when it comes to time and bookies shops. I want to play Henry Gondorff when we make a move about this. Anyway big blue through no fault of their own were hustled into making it all Java and CORBA so they could get this little bit of extra functionality without paying for it. The result was a clusterfuck. It was 10+ calls to get something achieved. So what's the lesson? User stories are the key to good API wrappers. By all means use the autogenerated stuff and put in place over the top of them helper classes to achieve things. You will never automate in place of just thinking about the problem, never. And once you have the problem understood, if its inefficient, you can adapt the base clases you have built above. The VCS toolset on CPAN (that im also blaming Leon for) is a great example of failure, the DBI and subsequent DBIx::Class toolsets are examples where people got it right. I actually despite its tumultuous start believe that DBIx::Class is one of the best examples of taking a good foundation (DBI/DBD) and standing on the shoulders of giants in the CPAN world and delivering a world class API - that in my opinion shames JDBC. G.
Re: API wrapper best practices?
On 03/23/2013 08:50 PM, DAVID HODGKINSON wrote: Are there any tutorial type docs for Moose Meta the way you used it or which man page should I be able to work it out from? Perhaps a course... http://perlschool.co.uk/courses/object-oriented-programming-with-perl-and-moose/ :-) Dave... -- Dave Cross :: d...@dave.org.uk http://dave.org.uk/ @davorg
Re: API wrapper best practices?
Message: 1 Date: Sun, 24 Mar 2013 09:59:37 + From: Dave Cross d...@dave.org.uk Subject: Re: API wrapper best practices? To: london.pm@london.pm.org Message-ID: 514ece89.1070...@dave.org.uk Content-Type: text/plain; charset=ISO-8859-1; format=flowed On 03/23/2013 08:50 PM, DAVID HODGKINSON wrote: Are there any tutorial type docs for Moose Meta the way you used it or which man page should I be able to work it out from? Perhaps a course... http://perlschool.co.uk/courses/object-oriented-programming-with-perl-and-moose/ :-) Dave... Actually I was about to point at something Moose-y that exercises a public API, such as DC's Net::Songkick. I was playing with this last year, and it's nice, but you always feel that you shouldn't need to roll your own classes. I guess the holy grail is something that takes the API schema and builds the classes on-the-fly, and is closer to what Dave Hodg is after. Ash
Re: API wrapper best practices?
On 24 March 2013 14:13, Ashley Hindmarsh ash+p...@best-scarper.co.uk wrote: I guess the holy grail is something that takes the API schema and builds the classes on-the-fly I don't know about holy grails but there's SPORE [0] which lets you describe RESTful APIs and automatically generate clients for them in different languages. There's a Perl implementation [1][2] but also implementations for Ruby, Python, JS, Node.js among others. If Dave's use case involves an API which can be modelled as a SPORE specification then it might suit him well - it handles the http client and call semantics parts, handing back perl hashrefs of the returned data. /joel [0]: https://github.com/SPORE/specifications/blob/master/spore_description.pod [1]: https://metacpan.org/module/Net::HTTP::Spore [2]: http://lumberjaph.net/misc/2010/09/17/spore.html
Re: API wrapper best practices?
On 03/24/2013 01:13 PM, Ashley Hindmarsh wrote: Actually I was about to point at something Moose-y that exercises a public API, such as DC's Net::Songkick. I was playing with this last year, and it's nice, but you always feel that you shouldn't need to roll your own classes. Yeah. While writing it I was always painfully aware that there *should* be an easier approach. But I never worked out what it is. All of which explains why Net::Songkick is now rather out of date compared to the API it models. I guess the holy grail is something that takes the API schema and builds the classes on-the-fly, and is closer to what Dave Hodg is after. That would be lovely. I'll take a look at SPORE. Cheers, Dave... -- Dave Cross :: d...@dave.org.uk http://dave.org.uk/ @davorg
Re: API wrapper best practices?
On 24 Mar 2013, at 13:13, Ashley Hindmarsh ash+p...@best-scarper.co.uk wrote: I guess the holy grail is something that takes the API schema and builds the classes on-the-fly, and is closer to what Dave Hodg is after. People thought of that, and now we have SOAP. So be careful for what you wish for. Sam -- Website: http://www.illuminated.co.uk/
Re: API wrapper best practices?
And now we have SOAP??? For me _at least_ SOAP came first On Sun, Mar 24, 2013 at 9:04 PM, Sam Kington s...@illuminated.co.uk wrote: On 24 Mar 2013, at 13:13, Ashley Hindmarsh ash+p...@best-scarper.co.uk wrote: I guess the holy grail is something that takes the API schema and builds the classes on-the-fly, and is closer to what Dave Hodg is after. People thought of that, and now we have SOAP. So be careful for what you wish for. Sam -- Website: http://www.illuminated.co.uk/ -- Best Regards, [Joseph] Christian Werner Sr C 360.920.7183 H 757.304.0502 Txt 757.304.0502
API wrapper best practices?
So I'm writing an interface to an API. It's a simple info request one. What top tips do we have for writing one that doesn't suck? I'd just go for a new that takes the auth info, methods to go fetch the information and being lazy, just let the data be accessible through the selfish hash. I'm not going to create objects for all the data objects at this point nor accessors for the individual fields. Well, maybe a few key ones. Suggestions for anything better, lazier, more modern?
Re: API wrapper best practices?
You mean apart from doing all the things you just said you're not going to do? On 23 Mar 2013, at 16:01, Dave Hodgkinson da...@hodgkinson.org wrote: So I'm writing an interface to an API. It's a simple info request one. What top tips do we have for writing one that doesn't suck? I'd just go for a new that takes the auth info, methods to go fetch the information and being lazy, just let the data be accessible through the selfish hash. I'm not going to create objects for all the data objects at this point nor accessors for the individual fields. Well, maybe a few key ones. Suggestions for anything better, lazier, more modern?
Re: API wrapper best practices?
If you're feeling lazy as you said, i'd say: provide methods with the same names as your API, and the same parameters. This way you avoid the need for much documentation. If you're less lazy and the API is not good enough, you might want to provide more explicit method names, as well as some more useful / complex methods. You might also want to make some parameters optional, or to give them default values; in which case you should document it.
Re: API wrapper best practices?
Probably, additional methods should not be part of the wrapper layer, but should constitute a just-the-next-layer.
Re: API wrapper best practices?
Really? Got a good example of where this is done and isn't a pain in the ass? On 23 Mar 2013, at 16:05, Mike Whitaker m...@altrion.org wrote: You mean apart from doing all the things you just said you're not going to do? On 23 Mar 2013, at 16:01, Dave Hodgkinson da...@hodgkinson.org wrote: So I'm writing an interface to an API. It's a simple info request one. What top tips do we have for writing one that doesn't suck? I'd just go for a new that takes the auth info, methods to go fetch the information and being lazy, just let the data be accessible through the selfish hash. I'm not going to create objects for all the data objects at this point nor accessors for the individual fields. Well, maybe a few key ones. Suggestions for anything better, lazier, more modern?
Re: API wrapper best practices?
If you want to be really lazy, do what I did in a very similar circumstance. I used Moose to create two classes, one which was a general purpose method to access the api, and in which was a factory object that created a 'Row' class. In that class I used the Moose Meta to create accessors on the fly for each data attribute. Better in my opinion than returning a nasty hash. - icydee On 23 March 2013 16:36, Pierre M piema...@gmail.com wrote: Probably, additional methods should not be part of the wrapper layer, but should constitute a just-the-next-layer.
Re: API wrapper best practices?
Are there any tutorial type docs for Moose Meta the way you used it or which man page should I be able to work it out from? Ta, On 23 Mar 2013, at 17:03, Iain C Docherty londonperlmong...@iandocherty.com wrote: If you want to be really lazy, do what I did in a very similar circumstance. I used Moose to create two classes, one which was a general purpose method to access the api, and in which was a factory object that created a 'Row' class. In that class I used the Moose Meta to create accessors on the fly for each data attribute. Better in my opinion than returning a nasty hash. - icydee On 23 March 2013 16:36, Pierre M piema...@gmail.com wrote: Probably, additional methods should not be part of the wrapper layer, but should constitute a just-the-next-layer.
Re: API wrapper best practices?
On 23 March 2013 20:50, DAVID HODGKINSON daveh...@gmail.com wrote: Are there any tutorial type docs for Moose Meta the way you used it or which man page should I be able to work it out from? Moose::Meta::Class and Moose::Meta::Attribute are probably what you want. I have an over engineered example here, https://github.com/OpenIMP/OpenIMP-APIClient/blob/master/lib/OpenIMP/APIClient/Loader.pm#L121 where a schema described in YAML is inflated into a Moose class hierarchy. Dave
Re: API wrapper best practices?
On 23 Mar 2013, at 21:19, Dave Lambley dave.lamb...@gmail.com wrote: On 23 March 2013 20:50, DAVID HODGKINSON daveh...@gmail.com wrote: Are there any tutorial type docs for Moose Meta the way you used it or which man page should I be able to work it out from? Moose::Meta::Class and Moose::Meta::Attribute are probably what you want. I have an over engineered example here, https://github.com/OpenIMP/OpenIMP-APIClient/blob/master/lib/OpenIMP/APIClient/Loader.pm#L121 where a schema described in YAML is inflated into a Moose class hierarchy. Hm. I'll look at this. In my use-case both APIs are going to poke stuff straight into a database so you're probably going tell me there's Cat Model stuff I should be doing too...?
Re: API wrapper best practices?
I don't think there's any special magic involved. Consider DBIx::Class::Schema::Loader or its opposite $schema-deploy https://metacpan.org/module/DBIx::Class::Schema#deploy Mostly integration with some existing system is a matter of ticking off all the detail and banging your head against any existing bits of the system that behave in interesting ways. This article also looks interesting. http://modernperlbooks.com/mt/2011/05/testing-dbix-models-without-the-database.html On 24/03/2013, at 9:51 AM, DAVID HODGKINSON wrote: On 23 Mar 2013, at 21:19, Dave Lambley dave.lamb...@gmail.com wrote: On 23 March 2013 20:50, DAVID HODGKINSON daveh...@gmail.com wrote: Are there any tutorial type docs for Moose Meta the way you used it or which man page should I be able to work it out from? Moose::Meta::Class and Moose::Meta::Attribute are probably what you want. I have an over engineered example here, https://github.com/OpenIMP/OpenIMP-APIClient/blob/master/lib/OpenIMP/APIClient/Loader.pm#L121 where a schema described in YAML is inflated into a Moose class hierarchy. Hm. I'll look at this. In my use-case both APIs are going to poke stuff straight into a database so you're probably going tell me there's Cat Model stuff I should be doing too...?
