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

[Randy J. Ray]

Andy Armstrong wrote:
> On 4 Oct 2006, at 20:40, Nik Clayton wrote:
>> 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.
> 
> The first - by exposing the API in perl you're already making it perlish
> - so you should use perlish naming conventions. The mapping is regular
> between perl names and api names - so it shouldn't be too huge a leap
> for anyone.

I *was* going to recommend the same, until he mentioned that there is existing
API documentation that the programmer will likely be referring to. In that
case, I would stay consistent with that documentation. I, too, tend to dislike
camel-case and only use it when coerced to (my CPAN modules do things the
Perlish way, but some paid work has been cc'd). But you're dealing with someone
else's API in this case.

(That said, this is exactly what I've done with the isbndb.com API I've
written, WebService::ISBNDB. They use camel-case in their XML and I provide
perlish accessors. But in this case, the existing API documentation is very
thin, and their REST interface only returns raw XML, they don't have an API,
per se, that offers camel-case accessors or methods. So I wasn't really
overriding anything by doing mine perlish.)

Randy
-- 
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Randy J. Ray      Westminster, CO    http://www.rjray.org   rjray at blackperl.com

Silicon Valley Scale Modelers: http://www.svsm.org