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...?