Why to Design a Good API

One of the most important challenges in the world of software design is designing a good API ((An application programming interface (API) is a set of routines, data structures, object classes and/or protocols provided by libraries and/or operating system services in order to support the building of applications. Definition of API on Wikipedia)) . Prominent software product development organizations are known for their wide developer network, extensive and helpful documentation, good support services and obviously: products that are worthwhile. Interestingly, a common thing between all these organizations is a “good product API” (stress: good).

From a business perspective

  • APIs help build a positive company identity by involving a large developer network.

  • It helps dilute competition by harboring partnerships and inter-usability of products.

  • By making one’s product be easily built upon, one can penetrate a larger market segment as other products build themselves around it.

  • APIs tends to become the most important asset to a company as it helps to bring about a greater ROI as the deployment targets get diversified.

  • Customer involvement is increased with the process of learning, writing, extending and innovating upon the API.

  • Attracts enterprise level customers and developers as they know that they have an extensible and documented base to work upon.

  • Helps to promote a scalable and expansible internal development process of a product.

From a developer’s perspective

  • In an API oriented design pattern, the Object Oriented or Modular Development processes are highlighted better.

  • Having a good API driven design pattern also allows easy maintenance of code as modularity is supposedly well maintained.

  • Support services are easier to provide as bugs are less likely to occur and are more likely to be identified faster.

  • Improves code quality as (besides modularity,) developers have a definite “direction” or target to be achieved.

  • Another important aspect of a well designed API is easy upgradability to new releases of a development framework/product.


What can a bad API do to you?

  • A poorly designed API will increase unnecessary support requests. Complicated and non-standard APIs tend to cause a large number of bugs in the final top-level application.
  • A bad API spreads the message that the company/individual does not care for its clients. This in turn, discourages developers and users from using the product.

  • An API is forever and should not be changed at whim. Once designed and popularized, it becomes the backbone of applications built around it. Hence, it is wiser to delay the release cycle than to save time on API design.


Characteristics of a Good API

  • An API should be easy to learn for all. In an ideal world, it should target both beginners as well as experts. This also means that the documentation should be done in a very lucid and organized pattern.

  • Applications built around it should be easy to implement. This means, better abstraction of the API, reduction of repetitive/stub coding by the end developer and offloading of common tasks within the API itself.

  • Self-explanatory API definitions make it easier to implement and less dependent upon documentation/support.

  • A popular API always has easy readability of codes for applications built around it. Easily readable codes allows faster support services.

  • Scalability and extensibility should be the part of a good API. It is not possible for a company/individual to develop any and everything that is conceived within the development cycle. Thus having an extensible architecture alleviates the possibility of adding features to your product even after it has been released.

  • Wherever possible, a good API should be platform independent. However, in a bid to make an API platform independent, one should not deviate from the general standards of particular platforms.

  • Another important aspect is the implementation of abstraction layers across all interfaces. An example would be to create a Database Abstraction Layer, so that developers have the ability to create their own set of routines to communicate with the database and subsequently the framework can boast of having the ability to connect to any database of choice.

  • As such, APIs don’t have any specific standard to adhere to. However, making APIs resemble popular frameworks of similar genre is a good practice. And even if that is not the case, an API should always follow a uniform pattern for standards and not surprise the users unnecessarily.

  • Extensive exception handling and fallback mechanisms make a good API tough to break or be breached. Good APIs generally handle exceptions themselves and allow developers to take over the post-exception routines.

  • Cohabitabilty and compatibility with other development frameworks ensure that none of the market segments of your product is blocked. It also adds to the confidence of end developers while developing around your framework/application.

  • A good API should not boisterously brand itself. Allowing developers to easily rebrand your Framework promotes your clientele. At the end of the day, if a large number of developers use your product, it will naturally be a hit.

  • Audience neutrality should be kept in mind while developing a good API. Not everyone can be satisfied, hence the level of dissatisfaction should be equal for all.

  • An API is never perfect. It evolves through implementations of feedback from users and through multiple development cycles. A good API strives to provide lesser but usable features than provide a large number of half baked ones.

Leave a Reply