API Wrapper Architecture Best Practice

Question

Hi,

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

This depends somewhat on the breadth/depth of API you're trying to wrap around.

If it only has a few simple API calls, the first approach is fine.

If it has VERY complex APIs that have "simple" mode you wish to expose to the user, one pattern is to have the main module and subclass it as Main::Module::Simple which would wrap around the main underlying module.

As you noted, a very broad API might benefit from being split into areas with parallel classes (possibly inheriting from or using a base class) responsible for wrapping each area. Just make sure to factor all the common stuff out to avpoid any code/design duplication.

Answer 2

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

(I also have a link to the slides, however StackOverflow allows me to post only one link per message).