What makes an API, a great API?

[adsenseyu2]

Before I start on this blog, lets take a look at the quote, “Being complex is easy, being simple is hard”. Do you agree? Well, I have experienced it and agree in totality. This is what it takes in creating a simple-to-understand-and-use API, a complex task. 🙂

Whenever I start writing about API, I do clarify what am I meaning for API? Most of the programmers would think if API is not same as interfaces to the classes that they write. Well, I would say that yes, they are same. However, we usually do not pay attention to write, what is called as “Great API”, as we write the APIs thinking that we shall only be using it in other classes and not many others and that it should be OK to name it appropriately as far as we can understand simply. However, the design of “Great API” demands the shift in mindset and requires the belief that API could be used by different software developers from different teams for different  ideas which may not have been thought by the author developer.

Start believing that API are one of the most valuable assets of the company!

Developers need to start seeing APIs as one of the valuable assets that company owns like any other applications. Supporting that I would say that a bunch of great APIs can actually make a company as very successful company. Look at Facebook, Salesforce, Twitter of the worlds.

So lets look at What makes an API, a great API?

• Coding Principles: Following are some of the coding principles one would want to keep into account while designing and writing APIs:
  • Should do just one thing and do it well: Well, I am inspired by Joshua Bloch Google tech talks video where he mentioned that A good API should do just one thing and do it well. It goes back to Single Responsibility Principle which talks about the same idea. Access the pdf version of Josh Techtalk on API of the video if you want to read at leisure.
  • Avoid leaking implementation details into API specification
  • Minimize Coupling: Plan to create components/modules that can be easily understood, built, debugged, tested and optimized at a further date.
  • Fail fast: APIs act like a blackbox and in case, things go wrong, developers have to adopt trial and error method to figure out what went wrong. To avoid that, one should plan to throw exceptions wherever and whenever possible to make sure that API developers understand the exception condition easily and take appropriate measures without spending a lot of time in trial and error method to discover what went wrong.
  • Avoid long parameter list: I have come across, many a times, such interfaces which consists of methods signature consisting of long parameter list. Well, if you are on API development, it would be nice to keep that in mind. Instead, you may use builder pattern to build an object consisting of those parameters and pass that object instead.
• Intuitive Enough: A great API needs to be intuitive enough that it does not require the software developers much time to figure out how it works. Meaning, based on API signature, the developer intuition should match on how the API should work vis-a-vis how it actually works in various different scenarios. For example, consider API such as length( object ). The “length” if passed with String should return length of the string and if passed with array should return length of the array in terms of number of object it contains. Lets take an example from real world. I have come across indicator device in many a car which works differently as it is placed differently. In some cars, it gets placed on left side of steering, and requires to be put up for giving indicators to turn right. In other cars where the indicator device in on right, it needs to be put down to drive to right. Thus, the behavior of indicator changes with car. This needed to be avoided while designing API. I would further go on to say that a great API should be easy enough to use and also, difficult to misuse due to its very intuitive nature.
• Names Do Matter: The API should be named in the manner that it behaves in accordance to what it means from its name perspectives. Simply speaking, API names should be self explanatory. The APIs should be aimed to read like a prose. This means that by looking at the API names, the developer should be able to guess what it is supposed to do. Also, names of API should be put in a consistent manner. Some API developers tend to use underscore between words, others join the words, still other join the shorthand of the words. Thus, it is good to think through the consistent naming patterns for the APIs that every developer need to follow.
• Appropriate Documentation: APIs are great when they are supported by great piece of documentation. Thus, plan to provide good documentation for your APIs. The documentation should primarily aim to cover all the edge cases which can occur while executing APIs such that developers should not cater to trail and error method for figuring out. Additionally, it is also good to plan to provide documentation on topics such as “QuickStart” which helps one to quickly get started with API setup and usage. Following could be made part of documentation of overall APIs:
  • Quickstart
  • API Reference
  • Advanced Guides
• Easily Maintainable: A great API should be able to be maintained in easy manner by other developers.
• Easily Consumable: API should be designed in the way that it can be consumed by other developers in an easy manner. In one of the videos that I saw

Following are some of the web pages which helped my create a better understanding of APIs design & development:

1. How to design a good API and why it matters?
   
2. The art of building a reusable class library
3. Martin Fowler API Design page