The purpose of APIs is to make software sharing and reuse as easy and straightforward as possible? Not necessarily so. At least, this is my conclusion after 2 weeks of working with Andrew Hicox on his wrapper for Remedy. Om my site, I prepared a brief list of what IMO makes a quality API. Going through this list, it appears that:
-- Yes, there is a description for its calls, but I have a strong feeling that, as in the old days of C libraries, this description is taken as the main, not minor part of the whole API package. To begin with, getting access to all necessary Unix directories and accounts was a terrible pain. I've not seen any make/ant/perl scripts to do this job.
-- To use Oracle, one needs access to sqlplus and certain SQL statements to check what is going on. The problem is, in the world of Remedy-ARSTools this is far from obvious. Hmmmm... OK, INSERT, UPDATE will blow Remedy up, but testing database app without SELECTs is the shortest way to disaster as far as I am concerned.
-- Once there is a working demo for at least some of API features, we are pretty much set. Also, it makes lots of sense to keep these demos as simple as possible, most importantly, mixing Remedy related logic with other advanced APIs such as SOAP is a real pain. Well... : -(((
-- There is not much that can be done about advanced API such as this one without simple, but reasonable logging scheme. Unfortunately, I've not noticed any.