Click here to Skip to main content
Click here to Skip to main content

Tagged as

Go to top

API design 101

, 19 Oct 2009
Rate this:
Please Sign up or sign in to vote.
There are striking lessons in failed software architectures, and it all starts with API design. I am sharing here my practical experience with C++ projects, but most of these advices also apply to Java.

I built up products from scratch several time in my professional life. Usually it starts with a very small engineering team –sometimes I was the very first member of the team. This is a great opportunity to lay strong foundations for subsequent software development, because one is in charge of the whole process. But one does not always have the chance to start from scratch.

I also worked with already established products, with larger team and millions of lines of already existing code. The typical software management and development project always offers some cumbersome legacy code and API that survive year after year. The reason is not so much that people do not want to fix the problem, but that fixing the problem requires a major product architecture overhaul, which comes to a prohibitive cost. There are striking lessons in failed software architectures, and it all starts with API design. I am sharing here my practical experience with C++ projects, but most of these advices also apply to Java.

Why is API so Important?

An API can be a company’s greatest asset: it captures communication and exchange of services in an application. A good API will naturally lead to more reuse, simpler code, and lower maintenance cost. If the API is public, a good API will also capture customers. There are examples of Java libraries that failed to be accepted not because they were inefficient, but because they very poorly designed.

An API can also be a company’s greatest liability: once the service has clients, one can no longer change the API! Suspending or rewriting an API is very pricey in terms of time and money. In the case of a public API, cost also comes in terms of reputation. A public API is forever: there is only one chance to get it right.

What is a Good API?

In today’s object-oriented software, writing an API is providing a service. Thus instead of thinking in terms of implementation and efficiency, one must first think in terms of modules and services: determine the usage model; establish the clients’ needs; and anticipate tomorrow’s needs.

Besides being powerful enough to satisfy the requirements, an API should be designed with two principles in mind:

  • Keep it simple! An API must be easy to learn and use, even without documentation. The API must be hard to misuse. Functionality should be easy to explain – if it is hard to name, it is likely a bad function. Use simple, consistent naming, and the code will read like a prose – Java libraries and STL are good inspirations for naming conventions. The API should be as small as possible: you can always add to an API, but you can never remove. A method should not take more than 3-4 parameters – else wrap the parameters in a class that can be augmented later.
  • Keep it abstract! An API must allow extension for future needs. For example, it should not assume anything about the implementation. It should minimize accessibility to implementation-specific details – an API, once public, will be used, and you do not want to expose the ugly details of a database.

In theory, an API should be written before going into some implementation. Gathering requirements is the first step. Requirements must be case-driven, specific, and should be questioned relentlessly until proven to be must-have. The API should then be written in the target language (C++, Java, etc): this will force the development team to make choices, and to keep the API simple and abstract enough – nobody wants to have too much to discuss! Then the API should be reviewed and made final in a public forum with the two principles above in mind: keep it simple (so that it is easy to support) and abstract (so that it is easy to extend).

An API should be documented, but well-designed APIs are sometimes self-explanatory. An API should answer the following questions about its components.

  • Class: what does an instance of a class represent? Is that a singleton class? Is there a factory? Who owns the memory?
  • Method: what does it do? What is the contract between the client and the instance? Is there any precondition and post-condition? Is there any side effect?
  • Parameters: What do they represent? Which information do they carry? Who owns them?
  • Exceptions: Who throws exceptions? What do they mean? What to do when catching one?

API and Performances

Bad API decision can limit performances. When designing an API, it is good to consider the following rules:

  • Avoid mutability. If a method returns a mutable instance, that instance needs to be created somewhere, which raises the question of memory ownership. Also mutable classes limit thread-safeness. Use ‘const’ whenever possible.
  • Avoid implicit call to copy and assignment operators. This is a waste of resources if you can use references. Declare these operators ‘explicit’ or ‘private’ to catch any misuse at compile time.
  • A factory is often better than constructors. A factory has full control on how instances are created and when they should be released (shared model, garbage collection, save/restore, caching and disk mirroring, etc.). A factory can return an instance of a sub-class.
  • Avoid exposing implementation details. It may prevent later improvements of a database. Never expose data members of a class, always use get/set accessors.
  • Question the thread-safeness of computational-intensive methods. One day the software may run on a grid or in a cloud.
  • Never compromise the rules above for a small runtime or memory improvement. For the vast majority of the applications, going a few percent faster is not worth the maintenance nightmare it can imply.

Final Word

A good API is a key to produce smaller and simpler code, which makes the product more stable and easier to maintain. Designing a good API is a collaborative effort, and a formal decision process is needed to freeze an API. A good API is hard to write, get your best people on it. And finally, a public API is forever. May these simple rules guide your next project.


Share: Add to FacebookAdd to DiggAdd to Del.icio.usAdd to StumbleuponAdd to RedditAdd to BlinklistAdd to TwitterAdd to TechnoratiAdd to Yahoo BuzzAdd to Newsvine

No related posts.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

ocoudert
Architect OC Consulting
United States United States
I have 20 years experience in software architecture and product development, including 10 years experience in research. I worked at eBay, Synopsys, Mentor Graphics, Magma, and I am an independent consultant in software design and development. I have published 50+ research papers or book chapters, and invented several algorithms for which I hold a few patents.
 
I am interested in technology as a whole, in particular software, hardware, and web-based applications. Check me out on LinkedIn or twitter (@ocoudert).
Follow on   Twitter

Comments and Discussions

 
GeneralQuestion regarding API Parameter. Pinmemberccpptrain26-Sep-10 23:44 
GeneralRe: Question regarding API Parameter. Pinmemberocoudert27-Sep-10 7:50 
GeneralRe: Question regarding API Parameter. Pinmemberccpptrain28-Sep-10 17:57 
GeneralGood one. PinmemberJackson Green30-Jun-10 23:48 
GeneralCould you provide some examples PinmembernetJP12L27-Oct-09 4:08 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web04 | 2.8.140922.1 | Last Updated 19 Oct 2009
Article Copyright 2009 by ocoudert
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid