Opinions: API wrapping, how close to original API should you stay?

[Nik Clayton]

Hi all,

I'm seeking opinions.  I'm in the middle of writing some code that wraps 
someone else's SOAP API.

The SOAP API returns XML that looks a bit like this:

   ...
   <OptimisticLock>...</OptimisticLock>
   <Id>...</Id>
   <ParentId>...</ParentId>
   <FullName>...</FullName>
   ...

Basically, CamelCase all over the shop.

I'm turning that in to an object, with accessors for the various 
elements[1].  One accessor per XML element.

Assuming you were writing to this API, would you prefer to use:

    $ml->get_optimistic_lock()

    $ml->get_OptimisticLock()

    $ml->getOptimisticLock()

to retrieve the value, or something else?

At the moment, I'm leaning towards the first.  It's simple and regular, 
but it does mean that the programmer has to translate in their head from 
the original API documentation.

The second lessens that translation slightly, but then the symbol 
inconsistently uses CamelCase and '_' to separate components.

That last one, to my eyes, just looks ugly.

N

[1] No, not just a hash ref -- debugging "$foo->get_optimistc_lock()" is 
much nicer than debugging "$foo->{optimistc_lock}".