Thought #1 on API Design

One thing that most programmers will need to do in their career is design an API that can be used by others. Don’t let anyone fool you, API design is an art-form, not a science, and not everyone is good at it.

Don’t get me wrong, I’m not suggesting for a second that the API’s that I develop are god’s gift to developers, I KNOW some of the API’s that I have created in the past have had warts, in fact some of them were complete festering blobs. Hrm, enough imagery, let me know in the comments if you want to know more about the crap APIs that I have written.

In the last month I have had the misfortune to experience two instances where a single class library has the same class-name used twice seperated only by the namespace. That by itself isn’t criminal, but what is criminal is that it is highly likely that you would want to have both namespaces referenced in the source file causing many naming conflicts.

The first offender is from Symbol, probably the largest provider of industrial mobile technology like ruggedised Pocket PCs and Windows CE devices. Symbol have a mobile SDK (sorry – its a login page) which includes managed APIs that allow access to many of the value added functions on their devices, such as bar-code scanning, mag-stripe card reading and more.

It so happens that mag-stripe reading and bar-code reading are so similar that they share a common base class – OK, I’ll go along with that. The problem is that they named the base class “Reader”, the bar-code reader “Reader” and the mag-stripe reader “Reader” too! To make matters worse, there is a “ReaderData” class which gets passed into readers, and that is subclassed using the same technique.

In order to make the type names unique Symbol chose to break the class libraries up using namespaces. So the fully qualified type names would be.

• Symbol.Generic.Reader
• Symbol.Generic.ReaderData
• Symbol.Barcode.Reader
• Symbol.Barcode.ReaderData
• Symbol.Magstripe.Reader
• Symbol.Magstripe.ReaderData

So basically I would need to use the Barcode namespace and the Generic namespace together in code so the types in one namespace is going to have to be fully specified in code. How did they end up with this implementation?

I can really only speculate, but I spent some time thinking about it yesterday and thought it might have been the outcome of some testing excercise where they wanted to be able flick between the types of readers just by flicking a using/Imports statement.

So, I said there were two examples didn’t I? OK, the final example is none other than the Enterprise Instrumentation Framework. I really like EIF, one piece that I particularly like is the event raising model where the specific events you raise supply much of the context that would normally be baked into a string.

If you are using EIF then you are more than likely going to need to implement a sink, and sometimes when you do that you are going to want to read configuration data from EIF, however, in EIF the configuration class for an EventSink is named the same as the EventSink base class (EventSink), once again seperated only by name spaces. Basically it has the same problem as the Symbol APIs.

OK – this has turned into a bit of a rant but really I just want to encourage people to try using their APIs before they put them out there, its one of the reasons that I like the harvest frameworks – they tend not to have this problem.