10 January 2013

API Design

by Pavel Penchev

This was one of the talks I was looking forwards to, since I have had the pleasure of talking with Pavel before and I know he has a lot to share on this topic. However I was disappointed that this talk took place in a crowded and hot small room and the words of the lecturer was barely audible. A real shame, but fortunately I was able to catch some of the things he shared with us.

Writing public API as opposed to writing internal API

We have all faced the challenges of writing APIs to some degree - however the problem becomes much more complex once we have to actually sell a public API. Then the design of the code, it's documentation and naming conventions, all of the things we usually consider internal, become part what we would usually expect from our user interface, they became the face of our product.
The topics in this lecure were mostly influenced by two very well written books:

  • "The design of everyday things" by Donald A. Norman - a book that is not strictly focused on software development but on the design of products as a whole
  • "Effective Java" by Joshua Bloch - which is a book that every Java developer should seriously consider reading

"The API is a business card to your company"

Natural mapping

Natural mapping is a design term, that implies that our products, e.g. our public API, needs to be designed in a such a way, that the user would find them natural to use. The first step to achieve this is to build a mapping between the intentions of the users and the way the API is designed. The next step would be to build a mapping between the structure of the domain and the API.
A very crucial point is to use the terminology of your domain. Many times developers tend to look at their code from an implementation point of view and use names such as "SystemEntity", "DOMTree", etc. These names, although accurate, do not translate to the user the purpose of the objects but rather translate the implementation specifics, which is not important to the user.

Mental models

A very important part of building an API is building up a model of each of the objects, their properties and how they interact. Unfortunately at this point I decided to switch to another lecture and my notes are cut of. Also Pavel has not provided his presentation online and I was not able to fill in the gaps myself, so here is where I leave this topic.

"Your code needs to be easy to use, easy to learn, but also hard to misuse"

Footnote : here is a good article by Joshua Bloch that I stumbled upon while writing this blog post on the same topic.