well that's it - I am not at all sure with OOP

You're approaching the problem of designing the API from the wrong perspective.

Describe a typical use case, not in terms of OOP, or any particular API, but in terms of how an application would need to use the functionality you are trying to encapsulate.

The key here is to recognise that once you know what an application needs to do with the functionality, 9 times out of 10, the API becomes self-designing...

Provided you don't get caught up with either:

• trying to utilise all the facilities of the OOP framework you are using;

  That is, just because Moose provides a bunch of facilities, you don't have to use them all.

• Trying to cover every conceivable use-case;

  Trying to predict all the possible different ways a piece of functionality could be used; and then design to cover them all, is a mug's game.

  A)You'll guess wrong, and predict uses that will never be used, and miss those that will; B) You'll end up with an API so complex and top-heavy that no one will want to use it.

Write down the use case that you currently have in mind. In words; code comes later.

Once you have described the application, then you should be able to extract from that the API requirements of that application; then design an api to fit those requirements.

Then mock up the API -- just empty subroutines/methods that verify the arguments and return a plausibly correct value:

sub new{ bless {}, $_[0] }
sub twizzle{ my( $self, $twizzleFactor ) = @_; ref( $self ) = __PACKAG
+E__ or die; $twizzleFactor > 1.0 && $twizzleFactor < 9.0 or die; retu
+rn 123.4567 }
[download]

Then write the (bare-bones of the) application, in terms of that API.

That process will quickly allow you to see the weaknesses and strengths; omissions and over-elaborations of the API design; and correct them.

And then you can fill in the guts of the API, using the bare-bones as your test rig.

Once the bare-bones application works, you can then speculate about what else... but don't do so before hand.

And along the way, the API design will (should) have fallen into place naturally.