Back to top

A Deep Insight Into APIs

1. What is API?

We all have heard about API or used them at some place or the other but most of us don’t have exact idea of what APIs exactly are and what they have to offer. This article will take you on a voyage through API world familiarizing you with different aspects of API and their growing relevance to technology and business. Please note that this article is mainly on web API but the initial discussion describes the general sense of API.

API is an acronym for Application Programming Interface. Lets break it to understand it better.

API = Application + programming + Interface

The word that instantly strikes is “interface”. Lets try to understand it, an interface is a kind of common boundary between two systems, which acts as a means and medium trough which two systems communicate. So here we go to give clear definition of an API.


“An API is an interface, implemented by an Application, which allows other Application to communicate with it, without exposing the details of the applications”

2. Why does API do?

Answer is, to allow communication between systems. Communication between two systems can be used for integration or to expose information and functionalities to other system. API makes any application or device capable of connecting to your service thus leveraging the power of web – wap – mobile – tablets and cloud. It gives a true multimodal sense to your application. Lets try to understand this with an example, Say you have collection of songs on your desktop machine. Traditionally to listen the song you will have to sit near to your computer. Imagine an Integration layer, which offers to expose your media library that can be easily consumed by a mobile app, by your IP TV, your in car entertainment system, a web/wap application thus making your media content readily available at your finger tip always and at your conveyance. Think how it will change your world. API is changing the face of Internet. The new internet relies more on an application then a browser, more on social connection then on traditional media and more on mobile then on desktop. API is making this innovation happen. Creators of Facebook, Twitter, Foursquare etc. have already proved this.

3. Types of API

Based on the way systems interact using the integration layer, I am classifying API into three broad categories.

Internal API

Internal API’s are the system specific API’s which offer integration point between internal systems and processes. Their main purpose is to bind the internal sub system and is invisible to outside world. These include API offered by SDKs to develop Softwares (Java APIs and likewise) , sub-systems and modules within the system.

Limited or restricted API

These sets of API are open for closed user group, which intend to integrate and are generally seen as integration points between organizations or business partners. Party interested in integration has to go through contracts and legal works to get access to API. They generally offer open standards for integration but can have their own protocol. Example belonging to this category includes API offered by Airline / Railways, Banks, payment gateways etc.

Public or Open API

These are the API’s, which are open to anyone and offer mainly information and functions with limited restriction. Main purpose of such API is to drive in traffic and revenue by opening common integration channel, thus allowing virtually any application or device to plugin and consume the information and functions offered to create what are called “Mashaps”. They generally use open standards like XMLRPC / JSONRPC, SOAP, REST etc. for data interexchange. These API are also termed as web API since they are mainly used in web context. Our discussion on API through out this document will be centered on web/open APIs

4. API economics

Most developer look at API as an interface for technical integration, one they use to access features offered by other applications and services in order to improve their own offerings. Although combining several technical components leads to an improved overall product for end users, but API’s are just not limited to this, they have far wider purpose.

-It offers an easy to integrate interface, thus allowing virtually any application or device to integrate with system.

-It makes it possible to consume different services offered from different APIs, thus fostering innovation.

-APIs are developer’s paradise and their bread and butter too. API delights developers as a channel for expressing their creativity and also making money

-It multiplies application reachability and drives in more traffic, thus making your brand more popular and business success.

-It helps information spread faster. With multiple applications and devices consuming the services offered by your application, the information travel at mush faster pace to its target.

-Foresters business needs

-Allows product and services to reach and sell through previously unused channels

-Helps collecting analytic information and trends

-Adds value to your service

-Gives social presence

-Lets you adapt to changing market behavior.

-Better promotions, reach in the form your consumer likes

5. Steps for designing API

a. Define the integration points i.e. API

The first thing to do is to define what are the processes and data you want to expose to the outside world. This is critical and most important step. You would like to consider your target audience who will be integrating with your system. Keep in mind your audience are just not developers but also the businessperson, who have to understand the integrations in terms of business needs before the technical stuffs begin. You should avoid using terms coming from the internal system, which actually wraps the information. Perhaps the best way to do is to analyze your system and find out the “nouns” like user name, place, country, product name etc. and “verbs” like “calculate”, “submit”, “retrieve” etc. as operations that can be performed on the nouns. You API should hide all system level details, for example you may have stored data in your database as “country” but from business perspective its may be better to expose the data as “Place”.

b. Map the APIs with internal system processes.

Once you have identified the data and functions you want to expose, next step is to map them to the existing legacy system and in case the system is build from scratch, you have to create the internal systems to support your API.

c. Implement the API

After you are done with mapping the API definitions to internal system, next step come is the implementation of integration layer. Implementation details go well beyond the scope of this article however there are several approaches to implement the public API.Our goal here is to expose the data and processes which will allow external entity to retrieve and process information from your system, you can achieve this using any platform and language that supports your platform. You can consume your system internal API to transform the data coming to and from the external public API hiding all internal details.

d. Make your API secure

Next action item in the priority queue is implementing the security to your API especially when you are exposing them to manipulate users data. Consider using OAuth and SSO.Try using SSL or message encryption to protect the data travelling between devices / Applications and your API.

e. Scale it

No we are not yet ready to go, before exposing your data and process to public you need to exercise the load and performance analysis. Getting a ballpark estimates of traffic coming from your API and doing load test on your system with similar load will help you prepare the initial load on your system. Use caching when necessary to avoid unnecessary resource utilization on server. Another option to prevent your backend system from collapsing in case of sudden surge in traffic is to adapt to cloud or virtual resource like Amazon EC2 etc. that will prevent the system burst.

f. Document your API

Before you release your API it’s very important to provide documentation on how to consume the API, Restrictions, best practices, as your API will be used by business partners, system integrators, mobile / third party application developers. Its best to provide online documentation, which keeps on updating. You should also include examples of invoking API is different technologies (like java, PHP, Ruby , .NET etc)

6. Points to consider while designing API


-Developer adoption

-Security: Identity, Authentication, Authorization


2. Common mistakes made while designing API

Missing API traffic and usage analytics information

1.Who is using and how mush are they using

2.How fast and good is your service

3.How does the API drive the business

Issues with traffic and scaling

1.Calibrating your API limit and quotas.

2.Deciding on right kind of rate limiting

3.Does your business needs quota on API usage

4.Monitor and respond to traffic management.

5.Deciding right kind of authorization and authentication.

6.Indecency exposure of data.

7.API design: Are you a pragmatist or RESTafarian

8.API user management

9.Ease of adoptability, API community and audience

Case Study: Twitter

Let’s go back in time and look at how Twitter started. It began as a pet project for the founders Jack Dorsey, Evan Williams and Biz Stone. They didn’t release it with a specific goal in mind, other than as a micro blogging service. They wanted to change the way information was shared in a more concise way, much like a text message.

They received a huge bump in usage at the SXSW conference in 2007, and early adopters started to use the service. Initially the early adopters used the service as a way to update what they were doing (ie. “I’m writing this article on LFY”), as many still do today. Not a lot of innovation, and certainly not that much use. It left many wondering if Twitter was ever going to really become popular, or even useful to the public as a whole.

But the real uptick in innovation (and traffic) came when Twitter released their API. The API has allowed countless mobile, desktop and web applications to utilize Twitter to spread information farther and wider than the founders could have ever imagined. Here are some of the creative applications that use Twitter:

StockTwits – A service for stock traders to find and share breaking stock news.

Tweets on Tees – Vote, submit and create T-Shirts from tweets/

Trazzler – Tracks tweets around travel sites.

Twestival – Find the nearest Twitter festival around you.

ExecTweets – Find and follow top business executives on Twitter.

And many, many more.

This list doesn’t even include the slew of mobile and desktop applications that you can use to update your Twitter status, as well as the countless services that have integrated twitter into their site (Facebook,Posterous, Tumblr, and many more).

Now that we’ve seen what an API can do for innovation and overall success of a service.


The Internet has changed greatly over the past few years. The web browser isn’t the only way to access web data, and mobile phones are becoming an increasingly popular way to browse the web. It’s imperative that you make it easy as possible for innovation to happen with your web service.

Release that API!

Think how powerful a service could be with hundreds or even thousands of developers making interesting applications and furthering your brand. Make it ridiculously easy to access your data.

on 04 Oct 2012 by
Rachit Gupta