com.kahaf.blogs.ishaq

Long Long Time Ago (that is about 6 months) when I was still a university student, I was a fan of Microsoft Technologies and a frequent visitor to Chad Hower aka Kudzu’s blogs (I have listened to him, and He is a very good speaker). Then, a paradigm shift occurred and I moved to open source…

The other day I saw a link to a Google Tech Talk by Josh Bloch on reddit and Boy! he is by no means a less addictive speaker than Kudzu.

Anyway, his talk was on How to Design an API, and the following roughly summarizes what I remember from his talk.

1. Why An API is important:

A good API is an asset to the programmer and the company. An API that is flexible and easy to evolve does not only maximize software reuse but also the testing time (since APIs code does not need to be extensively tested).

2. Why is it important to You (Or Me for that matter):

Because anyone who programs is an API Designer. Good Programs are usually modular and the inter-modular boundaries are APIs themselves. Good APIs tend to be reused, and if an API is being used by a couple dozens of people, it is important that You code it right the first time, once it is out in the public, Changes cannot be made at your will.

Also, thinking in terms of API Desin tends to make you write good independent units, instead of just hacking a solution.

3. Characteristics of a Good API

1. Easy to use even without Documentation
2. Hard to misuse
3. “sufficient”ly powerful to satisfy requirements (a powerful API doesn’t necessarily make it a good API, If an API satisfies the requirements, it’s good)

Rest was blah blah blah.

4. Requirements Gathering:

Mostly people suggest solutions instead of stating their problems, it’s upto the API designer to determine the requirements. For Example, a requirement might be to clean the server cache every 2 hours, where the real requirement could be to improve server’s performance in terms of memory utilization. A good tip to reach the actual requirement from the suggested requirement may be to ask “Why do you want it?”

5. Start with a short specification:

Long specifications are hard to maintain. Expand the specs as you gain confidence through coding. Write code to the API even before writing the API.

6. Maintain Realistic Expectations:

You cannot please everyone, so you should try to displease everyone equally i.e. the API should be written in such a way that Everyone can find use for it, it may not excite everyone, but it should be good enough to make everyone consider it.

7. Make API as small as possible:

Only provide the necessary functionality and specifically “When in doubt, leave it out”

8. API should be tied to a particular implementation:

This is specially true in case of return values and exceptions that are thrown. Make sure that your return values (and exceptions) are at the same level of abstraction as the API e.g. returning a HashMap is tying the method to a particular implementation.

9. Minimize Accessibility of Everything.

The more access you provide, the more difficult it is to change the API later. In fact, unless there are reasons for a class to be sub-classed, declare the class as final, and if the class can be sub-classed, clearly mention (in the comments) the expected ways to do so. Don’t make this serialization, you are potentially provide access to the data.

10. Names and Documentation Matters:

API is like a language, use good names, and document rigorously.

11. Rules for Documentation:

• Class: Describe what an instance is
• Method: Contract between the client and the method, preconditions and postconditions and any potential side effects
• Parameters: Describe the unit of parameters (e.g. time), form (e.g. xml) and ownership (whether the caller still has it) of the parameters

12. Design decisions can affect the performance:

True that Premature optimization is root of all evil, but thoughtful decisions at design time can save a lot of optimization later.

13. API must coexist with the platform:

14. While translating an API, DO NOT Transliterate:

i.e. don’t just translate the code line by line from one language to another, instead write the code that provides same functionality on the target platform.

15. Class Design:

• Minimize mutability (that’s a general rule anyway)
• Sub-class only when there’s a need for it

16. Method Design:

“Don’t make the client do what the API can do” e.g. boiler plate code in Win32 API. Such code is normally copy-pasted and is error prone. Do such house keeping in your own API.

Follow the principle of Least Astonishment, A method should do what its name suggests it does and nothing else e.g. in java, thread’s “interrupted()” method does not only return the interrupted status of a thread by it also clears it. it is BAD

Fail Fast, If something has gone wrong, tell the client as soon as you can. Throwing an exception 20 function calls later that the expected parameter was a String which could be parsed to a valid integer will only make debugging a mess…

Provide programmatic access to the data that is available in string form e.g. java’s Exception doesn’t only provide “printStackTrace()” (which returns a string) but also “getStackTrace()” which provides programatic access…

and finally use a consistent parameter order through the system i.e. if the first string to string manipulation method is source string, it should be so through out the system.

That’s a lot of stuff I have recalled, and before writing this post I didn’t think I would remember this much :). However, according to Josh, if you remember two things from his talk, you have gained very much, and these two things are:

1. When in doubt, leave it out
2. Don’t make the client do something that the API can do

Need to leave the office, next post will most probably be a strange return value bug in a module today. Although, it was found quickly, but it was something quiet surprising. more on it later…

written by ishaq