API Design

My discussion about easy scripting of web apps is part of the subject of API design, which I do find very interesting. API choice is subjective, but is it that subjective? There should be examples of APIs everyone can point to and say "That is how/how not to do it".

Obviously, I'm a fan of object-oriented APIs, but the ease of use of OO APIs differs greatly.

Python's standard API is too flat. The modules are self-contained rather than having dependencies on one another. This means most functions will tend to return a primitive rather than a more suitable datatype. There is little consistency in naming, but that's not too bad because of the interactive interpreter and help.

Java's API is too nested. It is highly interdependent, but its power usually comes from composition of the objects rather than subclassing, so some of the packages get extremely complex. It is entirely based on design patterns and has a consistent verbNounPhrase naming policy which they only break occassionally (*cough* System.currentTimeMillis() *cough*). I think I prefer this to any other API I've used, despite areas of high complexity and still not having found a truly succinct way of using AWT and Swing (perhaps I will try a XUL implementation next time).

The worst API I've ever looked at is libxml2, minor faffing with which is required to get XSLT up and running in Python. It's so bad it gives me a headache just looking at the API documentation!