API Design Paper Summary
Introduction
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:
- Easy to learn and memoize
- Leads to readable code
- Hard to misuse
- Easy to extend
- Complete
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 toAvoid 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.
Good jjob
ReplyDelete