The May 2009, edition of the ACM Communications magazine had a great article about API design. The author described in great and insightful detail some of pitfalls, and common mistakes that API designers make. The entire article is worth reading, but if you want the elevator pitch, here it is.

Many API’s are poorly designed since the designer is the implementer and is too close to the code, therefore assumptions are made too often and are too often wrong. The implementer also assumes that the consumers of their API will be similar to them, when in reality there is no reason the consumer will be anything like the provider.

What struck me about this article is that you could replace API design with Design.

Think about it, everything that I just said about API design is true for design in general. More often than not, the design of the software, (especially web applications or internal applications) is done by the people writing the code and stepping into the shoes of the person using the software is not a skill that most developers posses out of the box.

Treating API design as a subset of design; maybe we can apply some of designs best ideas and best practices to API design. Two of those best ideas I will argue is User Centered Design and Participatory Design, both of which could be and should be applied when designing an API.

User Centered Design (UCD) is focused on the user. The idea is to design a solution around a given population of users that are already solving the problem you are trying to solve, but perhaps in a sub-optimal way. UCD is therefore a joint effort between stakeholders and software designers since many aspects that might be cool and compelling to software types, have little to no value in the real world. UCD involves heavy user feedback at all stages of development. Ideally, iterative design is used so that small incremental changes can be tested with users, feedback can be acquired and then incorporated into the next iteration. This process is what formed the basis of iteration cycles in Agile Development, Extreme Programming and Scrum, while it has become very popular recently, it has been used in Academia for over 20 years, namely from Ron Baecker, Bill Buxton, Ideo and many more…

Participator Design (PD) takes UCD to a new level by concurrently involving stakeholders throughout the design and development process. The idea is to remove the separation between producer and consumer, thus making the users active members of the development team. The key to PD is not to simply pay the users or domain experts lip service, but to give them real, authoritative roles in the design of the product. Users actively write, discuss, vote and even veto features. This keeps the developers humble and ensures that only usable and practical features are included. At the same time, developers can chime in with innovative ideas that users might have never thought of given their backgrounds and engineering expertise. (There is a great podcast from the guys at the Java Posse talking about Design and Engineering, check it out if you are interested) If done correctly, PD can be one of the most powerful design tools. So why doesn’t everyone use PD? Well, it can be more expensive up front since you need to find a domain expert or two or three, have frequent design meetings and training sessions bringing different groups up to speed etc… therefore the process tends to take more time. However, there are often fewer problems and more users once it has been released, so the trade off is a worthy one.

So bringing this back to API design. I believe that UCD and PD can drastically help API design and should be employed by companies who are API heavy or even for everyday Joes looking to make a new API for a given service.

I have had the pleasure and pain of writing and using a variety of different API’s. Some of the best, are from Apple and Google. Apple’s iPhone SDK, while massive and complicated, becomes intuitive after the initial barrier of Objective-C gets out of the way. Google tends to like REST, and simple URL based APIs. My guess is that since Google needs to use their own APIs and SDK’s much like Apple, they are very well designed. Microsoft has some good ones too. Their Windows Mobile API and SDK are top notch! In fact, I have lots of fun writing Windows Mobile Applications, that being said they are not nearly as well thought out as Apple’s iPhone SDK. Even though they have more documentation, Apple tends to self document, whereas Microsoft often has two methods for doing the same thing, or slight variations that make it hard to know what the side effects will be. Again, this is personal preference, obviously some people HATE the iPhone SDK due to its poor documentation and MVC architecture, however, once you start using it, you see it’s real power: self documentation and reuse of common design patterns for solving different problems (think Delegation).

Looking back, it would have been cool for either of those companies to ask users what the API should like it. Go out into the wild and give users a bunch of different options for calling the same core method or preforming the same task and see which one the users prefer. Even better, setup a website similar to UserVoice where users can vote on the API they want. The new Google Analytics API looks like it was designed for users, since it’s so clean and simple. It reminds me of Ruby and one of the things I love about it. When I am teaching ruby to someone and write the following…

irb> (1..4).each { |number| puts number }

I really don’t have to explain what it does. It self documents. I heard that Matz, the creator of Ruby, would constantly show the language to colleagues and have them play around with it. They would give him the feedback and he would iterate. I am saying that there should be more of this. We need more User Centered API Design and Participatory API Design. I know that it seems like common sense and unfortunately many design principles, when written down or discussed seem like common sense, but the fact is they aren’t being applied. If they were, there would be less crappy APIs.

I promise the next time I am designing an API I will employ these methods and report back on how it goes. I really think this could work, and could go a long way to making sure that another article doesn’t have be written 25 years from now in Communications complaining how we have solved teleportation, our energy problems and have made headway on the meaning of life, but still have terrible APIs.

Thanks very much, let me know what you think,

Kent