API Wrapper Architecture Best Practice

Question

I'm writing a Perl wrapper module around a REST webservice and I'm hoping to have some advice on how best to architect the module.

I've been looking at a couple of different Perl modules for inspiration.

Flickr::Simple2 is basically one big file with methods wrapping around the different methods in the Flickr API, e.g. getPhotos() etc.

Flickr::API is a sub-class of another module (LWP) for making HTTP requests. So basically it just allows you to make calls through the module, using LWP, that go to the correct API method/URL without defining any wrapper methods itself. That's explained pretty poorly - but basically it has a method that takes an argument (a API method name) and constructs the correct API call, e.g. request()/response().

An alternative design would be like the first described, but less monolithic, with separate classes for separate "areas" of the API.

I'd like to follow modern/best practice Perl methods so I'm using Dist::Zilla to build the module and Moose for the OO stuff but I'd appreciate some input on how to actually design/architect my wrapper.

Guides/tutorials or pointers to other well designed modules would be appreciated.

Cheers

Answer 1

Joshua Bloch has good tips on "How to Design a Good API and Why it Matters" (video, 2007).

The slides (PDF).