Library design.

Yesterday I was looking for a library to extract some data from a well-known website.  The website in question has a rich REST-based API that allows you to retrieve and edit your content on the site.  As with all good Web 2.0 services, there is a considerable flora of libraries for different languages to interact with the site.  (I have omitted naming the library in question since this isn't a critique of that library in particular, but musings over sloppiness in general)

However, after surveying the libraries available in the programming language I wanted to use I was somewhat disappointed.  Of the two libraries available, one isn't being maintained anymore and the other...well, the other isn't really a proper library as such.

The point of creating a client library for an API is twofold.

First and foremost it is a mechanism for just making the primitives of the API available to the programmer -- or in a more abstract sense, to map between languages.  The languages being, for instance, the REST API you want to use and the programming language you use to interact with the API.  For the most part this is just grunt-work and often requires very little thinking.  Indeed, for Web Services this is, in principle, just a matter of pointing a WSDL parser to some definitions and have it generate the code you need. (In practice this process is very fragile when it comes to Web Services, but that is a different discussion).

The second task of a client library is to hide ugly implementation detail, and if possible, introduce a convenient model for interacting with the low level API without having implementation details seep out between the cracks unnecessarily.

The library I was faced with went to great lengths in capturing the full breadth and depth of the underlying REST API.  Sadly it did not provide a meaningful model for interacting with the service.  Just by inspecting the API documentation for the library it was relatively cumbersome to divine how you would perform a given task.   It would only make sense if you first studied the underlying REST API and then imagined how a lazy programmer would map these concepts into a programming language.

But the worst aspect was the leakiness of the library.  Not only did it force you to bother with the idiosyncrasies of the underlying REST API, but the damn thing was leaking implementation detail as well.  In particular, at every turn there were cascades of exceptions being thrown that would not make any sense to an application programmer. 

For instance,  there is absolutely no point in throwing bare XML exceptions from the XML parser used by the library.  What is the application programmer supposed to do with them?  They convey no meaningful information at this abstraction level and when these exceptions do occur the only code in any real position to make sound decisions on what this means and how this should be handled is the library.

There is another issue of a more fundamental character.  By throwing these exceptions, generated by dependencies of the library, you force the user of the library to depend on these libraries as well.  Not a good programming practice.

If you create a client library, using it should save people work.  Not generate more work.

1 comment:

  1. I feel your pain on this. I was looking at libraries to handle OSC messges. My conclusion is that I need to use the existing library for _some_ things, but I really need to write a sane wrapper to abstract away all those bits that _should_ have been abstracted away in the first place.