Skip to main content

API Design Paper Summary and Review

API Design Paper Summary


Is building API a solvable question, how far can we get into having good API’s and what is a good API at all? these are all very hard questions, usually you know the answers once you designed multiple APIs and got experience and then reviewed the decisions you have taken. Fortunately there are papers dealing with this problem exactly, for complex API’s used by a huge amount of people, the Qt API for example a very populate framework for desktop GUI building, and today we are going to go through a summary of that paper.

“The Little Manual of API Design” is a very nice paper written by Jasmin Blanchette has released a paper while working in trolltech, which is a Nokia company. I found it to be very clear and concise, and reassuring what we think of API design. It’s a difficult task that includes both artistic, social, programming and scientific skills. We are going to summarize this paper for you.

When you write an API you combine a set of symbols and export it for users to use, so that they can build their applications on top of your API. You can think of an API as one of the major abstractions of your software, this is the abstraction that users are going to see, it’s the language of the library, this is the external meaning of your library, and when designing it its going to effect your whole software design.

In this paper Jasmin is going through the lessons she learned by designing one of the most used GUI library which is used heavily in many applications that you use on a daily basis, this is the QT library used for building GUI for desktop applications which they built at Trolltech which is now part of Nokia.

The characteristics of good API’s

The paper describes a list of what makes a good API, this list is inspired by Joshua Bloch (the creator of Java collections API and the author of effective Java book).

For an API to be considered a good API it should be:

  1. Easy to learn and memoize
  2. Leads to readable code
  3. Hard to misuse
  4. Easy to extend
  5. Complete
What about minimal API and consistent it does not appear in the list? Isn’t it important, well actually the answer from the paper is that if it’s not minimal and non-consistent it would not answer bullet number one it would not be therefore easy to learn.

Easy to learn and memoize

So when you design your API make sure it’s easy to learn, to make it easy to learn to reduce the cognitive load on user by making it more consistent, having conventions and patterns, so user can move fast from API to API, a minimal API is more easy to learn than one which is not compact.

I used in the past an API that required me to write a lot of code just to call an API, that is not an easy to learn nor use API, you could add for that purpose convenience methods which does all the boilerplate instead of the client calling the API.

The paper then moves on to share what it’s view on convenient API, it moves ahead to say that if you have a method for addItem(index, item) then a continent API could be the same method without the index with default or that if you have an API that instead of a function or constructor receiving multiple parameters you can split it with builder or with multiple setters.

This is pretty obvious and I’m a little disappointed at this point in the paper, because if you already know you need a property in an API and you need to decide between one function that receives multiple params to multiple functions that receive each one param, this is the best case, the real challenge in API design is when you are not sure if the API should contain at all one type of parameter versus another, do you want large, medium, headers or do you actually want the user to specify the exact size of the header, this is the real challenge.

Hard to misuse

Easy to write correct code than incorrect code. Example HTML API designers originally recommended its users to use <strong> rather than <b> but as <b> is much easier and even easier to remember then users did not do that, but if <b> was <font style=“italic”> in most cases users would prefer <strong>

As much as I like these recommendations these are still dealing with technicalities and not with the real issues with API design which is what should appear at all in the API which is a tougher question.

Easy to extend

Libraries grow over time, and API’s should be designed with this in mind. How do you do that? How do you design an API that is easy to extend? If you accept an enum in the API, you could introduce a new enum value for users to use. If you abstract the inputs in objects you could add new fields to these objects.

API’s should be complete

A complete API is an API that allows users to do everything they want to do with the library abstracted below it. It’s impossible to be fully complete, but the important thing here is to allow your API to get complete over time, you do this with the previous item the ability to extend it. So that each enhancement of the API is one step forward into completeness.

Designing an API

Next we investigate some guidelines to enable you to have a good process to design your API.

Know the requirements

Solid requirements’ knowledge are the basis for a good API design, before you solve a problem you first need to know the scope of the issue well, in many cases you are solving the wrong issue, you must know the problem that users are trying to solve, this is what your API is going to answer, so you better know damn well the question, it could be the case that the user’s themselves don’t know the question but only think they know the question.

Design the API before implementation

If you go straight to the implementation it’s like coding before thinking, if you design the API before understanding the use cases, this might result again in wrong API, and a well design wrong API could be worse than less well-designed but correct API!

Look for similar API’s in the same library

This pretty many goes without saying when you add/update API for a library check the existing API’s conform to them use the same terminology and learn from them.

Peer review the API

I have nothing to add on this, as API could be an irreversible implementation you must do whatever you can to get feedback before you release it.

When in doubt leave it out

If you have your doubts about an API or functionality, you can leave it out, or mark it as internal, and reconsider it at a later point. It often helps to wait for feedback from users. On the other hand, it is practically impossible to add every feature suggested by users. A good rule of thumb is to wait until at least three users have independently asked for a feature before implementing it.

Write several examples against the API

After you design the API write examples against’t the API I’m sorry but I have to say this is very trivial, I will share my own insights about API building below, but as much as trivial that is its super correct and you should never neglect it.

Prefer specific names to general names

Remember that names occupy API real estate: Once a name is taken, it cannot be used for something else. This is especially an issue with class names, since a library might contain hundreds or even thousands of classes that need distinct names. Another reason for preferring more specific names is that they are easier for users to relate to

Avoid making your APIs overly clever

We observed earlier that the semantics of an API should be simple and clear, and follow the principle of the least surprise. If an API is too clever (e.g., if it has subtle side effects), the users will not understand it as well and will find themselves with subtle bugs in their applications. Cleverness also con- tributes to making the code less readable and maintainable, and increases the need for documentation.

Personal Take on API design

While you should do your best to predict the use cases, my personal take is this, do whatever you can to get early adopters for the API that you have control of meaning, experiment with the API try to have enough time even to be yourself a consumer of it, convince people to be early adopters to test the api try, it does not matter how smart you are, you would not be able to predict the requirements, so experiment, even if you think you cannot experiment, try at least to get some time were you are a client or find clients for your api. Unfortunately the paper did not deal with this, I think it had good tips, but those are not the hardest questions in API design, in fact those are the simple questions, but it’s a fine paper nevertheless.

There is also a notion that says that API should scream while this sounds too extreme for me this means a few things, API should be specific and not overly generic instead of get use getTaxi in this way you look at the api and you konw what it’s about, it’s about taxi it’s screaming about it, it’s easier for users to use.

As we already talk here is another tip, find an API that is heavily used that has a very similar use case to yours, see which API they exposed, you could learn then to experience from real users using

Communicate about the intended API, so you can’t find users to use the API and you still want feedback, best to send the expected API to consumers and gather feedback, this does not mean that you need to align with what they suggest but in many cases even the process of writing the summary of that API and sending to consumers would already raise up some additional feedback.


When designing an API first be super sure of the question you are trying to solve then understand the solution then think of the API review as much as possible write example tests share with friends hoepefully with clients be prepared for mistakes be specific make it easy to understand the api.




Post a Comment

Popular posts from this blog

Functional Programming in Scala for Working Class OOP Java Programmers - Part 1

Introduction Have you ever been to a scala conf and told yourself "I have no idea what this guy talks about?" did you look nervously around and see all people smiling saying "yeah that's obvious " only to get you even more nervous? . If so this post is for you, otherwise just skip it, you already know fp in scala ;) This post is optimistic, although I'm going to say functional programming in scala is not easy, our target is to understand it, so bare with me. Let's face the truth functional programmin in scala is difficult if is difficult if you are just another working class programmer coming mainly from java background. If you came from haskell background then hell it's easy. If you come from heavy math background then hell yes it's easy. But if you are a standard working class java backend engineer with previous OOP design background then hell yeah it's difficult. Scala and Design Patterns An interesting point of view on scala, is

Alternatives to Using UUIDs

  Alternatives to Using UUIDs UUIDs are valuable for several reasons: Global Uniqueness : UUIDs are designed to be globally unique across systems, ensuring that no two identifiers collide unintentionally. This property is crucial for distributed systems, databases, and scenarios where data needs to be uniquely identified regardless of location or time. Standardization : UUIDs adhere to well-defined formats (such as UUIDv4) and are widely supported by various programming languages and platforms. This consistency simplifies interoperability and data exchange. High Collision Resistance : The probability of generating duplicate UUIDs is extremely low due to the combination of timestamp, random bits, and other factors. This collision resistance is essential for avoiding data corruption. However, there are situations where UUIDs may not be the optimal choice: Length and Readability : UUIDs are lengthy (typically 36 characters in their canonical form) and may not be human-readable. In URLs,

Dev OnCall Patterns

Introduction Being On-Call is not easy. So does writing software. Being On-Call is not just a magic solution, anyone who has been On-Call can tell you that, it's a stressful, you could be woken up at the middle of the night, and be undress stress, there are way's to mitigate that. White having software developers as On-Calls has its benefits, in order to preserve the benefits you should take special measurements in order to mitigate the stress and lack of sleep missing work-life balance that comes along with it. Many software developers can tell you that even if they were not being contacted the thought of being available 24/7 had its toll on them. But on the contrary a software developer who is an On-Call's gains many insights into troubleshooting, responsibility and deeper understanding of the code that he and his peers wrote. Being an On-Call all has become a natural part of software development. Please note I do not call software development software engineering b