Understand the Importance of API Design by Earlence Fernandes and Boris Farber

The time in the IT Industry (the most important factor by which the company performance is measured) and API Design are connected stronger than we expect on a daily basis.

1.      Release date

Software development firms continually strive for shorter development and release cycles.

-         Want more releases in shorter spans of time.

-         Can be achieved through re-usable code/libraries in the form of good APIs.

2.      Competitors

-         Having a set of good home-grown APIs can be a competitive edge over rivals as it forms intellectual property.

3.      Money

-         Time is money. Shorter development time results in lesser costs and can be achieved thought a good style of programming (which is promoted by good API design).

When somebody else (or even you) uses your API that person spends his company's most important resource - time.

The time needed for:-

1. Evaluate APIs does it suit my needs? What are the costs of using this API? Is it too powerful for my needs? Technical factors such as size, efficiency etc.

What you can do?

As an API Designer, you can provide a ready cheat sheet with all major features/factors of your API set. This provides a nice one point of reference.

2. Download your library. Will it cost money? Is it Open Source? What are the intellectual properties rights guarding its use?

What you can do?

Most Open Source projects provide software under a very relaxed license. Many come as free, flat free others may charge a small royalty. These are some options, you as an API designer can take advantage of. Voluntary donations are popular nowadays. It also serves as a good feedback mechanism because; people will donate only if the library was good!

3. Find starter stuff. How well documented? What is the learning curve?

What you can do?

Provide really good documentation. Provide more examples. A startling discovery is that most good open source libraries provide a few examples, but not nearly enough. Improvement needs to be done here. Eg: The Jingle extensions present in the Smack library from Jive Software provide a few examples, but they are not enough to grasp the entirety of a library as complex as Jingle.

4.Do a Hello World program ubiquitous for any new learning. Moreover, time needs to be invested in the learning task.

What you can do?

The API designers should provide detailed steps with ready code to run. Most developers like to see something running before they actually like to get down and start learning the internal mechanics of the library.

5. Integrate into the solution. Before the final integration, a check must be made to see how well the API/lib can be integrated. Is it seamless? What impacts will it have on my overall architecture?

What you can do?

Provide sample integration architectures, sample use cases etc.

By providing well designed API you save your clients the troubles associated with many problems. Don`t forget; treat your client`s right. They are smart developers, who want to do their job and if your API costs them time, this is your problem!

Don't forget, in case your library is Open Source your clients are using your API to save their time. The clients could develop such a library by themselves. Thus if the clients spend too much of their time on your product, you did an unsatisfactory job. In case your library is closed source, the right API builds a better relation with your clients.

Thus, as Bloch notes, API is a key company asset and liability. Satisfied clients might generate more buzz and bring other clients via their blogs, promotions and other activities. So an API well designed generates your company revenues, in addition, you position yourselves better than your competitors

Today's news spreads fast. The internet, blogs and search technology provide large amount on information at a mouse click. The web is updated with a new content in the blink of an eye. Thus if your API is good you can attract new developers or customers easily. But if your API is bad and causes problems to users, your API will result in losing customers and creating a bad name for the company.

Thus the most important item to understand is appreciating the importance of API Design and its value to you, your business and your clients.

What defines good API?

The answer to this question is deceptively difficult to derive, but it is one we intend to answer, hopefully, to the satisfaction of our readers.

There are several points on which an API maybe judged, each more important to some than to others. Designing a good API is not a day's task; rather, good APIs are evolved through time. We list some points, which, at a very superficial level may be used to evaluate an API.

The Call to Functionality Ratio

This basically answers the question, “How much work is accomplished by one API call. A well-designed call should only do what the name indicates e.g.: printf(…) is the well-known C function to print data to the console. It does not give the option to set the color of the output etc, it just simply does what its name says, that is, print to the console.

Size and Complexity

This general parameter focuses on the entire API set. Some APIs are complex just because they are designed to solve complex problems. On the other hand, some are simple. The major point to note here is that however complex the problem being addressed,complexity of use and learning should be kept in mind. Size is an obvious factor and mostly depends on the target execution environment, e.g. for a constrained system, like a real time OS or a cell phone, the footprint has to be small so as to fit comfortably within the environment and not cause any problems.

Inclination to adaptation (plug-ins)

No API can be designed to suit all the needs of all its users. Adaptation allows evolution and evolution implies survival of the fittest. This means that your API can be there for a long time and evolve as technology evolves e.g The Eclipse IDE and the Eclipse Plug-in Framework.

Ease of use and learning

This is what will finally determine the overall success of an API. No one likes and API that is inordinately complex and difficult to learn, although it maybe sufficiently powerful enough for the task at hand. Simplicity matters. One of the best examples is Java Collections Framework (Bloch) that provides easy and convenient interfaces for working with data.

Summary

1.      Evaluate how much time you are losing by learning new APIs and applying the newly learned API badly.

2.      Make a list of actions how can you decrease the spent time from the first section.

References

1.      Practical API Design: Confessions of a Java Framework Architect
Jaroslav Tulach
http://wiki.apidesign.org/wiki/Main_Page

2.      How to Design a Good API and Why Does it Matter
Josh Bloch
http://lcsd05.cs.tamu.edu/slides/keynote.pdf