Almost every big company allows its data to be accessed by apps made by others. Facebook allows you to use your timeline on your own website. So does Twitter. On the other side, both services allow data from other sites to be shared on their timelines. You can make mobile apps that access the details of a user if his/her Facebook account is linked with your app. In fact, so many apps do not use their own login system, but rather use a service like Facebook, Google+ or Twitter to manage sign-up and login. How is it possible for you and so many other services to integrate so seamlessly with these world-renowned services? It is because these services provide a way to connect to their system and fetch and modify their data after sufficient authentication. This way of connecting to a service from another service is possible through a system called an Application Programming Interface (API). APIs have evolved rapidly and today it is possible to make connected, flexible and easy-to-integrate services using REST APIs. In this post, we will understand what an API is.

Understanding APIs

Let us consider a ceiling fan. I am wound up cosily in my couch, reading a nice book. But the day is warm and I could do with some cooling down. The only way to turn the fan on is to get up from my cosy position, walk upto the switchboard and push the two-way button to the ON position. The fan turns on. Let us pause here for a moment and slow down the steps between my tapping the button to the ON position and the fan turning on.

There is a circuit of wires that runs between my home’s power supply box and the ceiling fan. The positive terminal of the supply box runs to the positive terminal of the fan’s motor. But there is a caveat. If the two wires were to be connected all the time, the fan would always receive power and run forever, even when you don’t need it. Hence, on one of the wires, typically on the positive terminal, there is a device called switch and you see it on your switchboard. The work of the switch is to keep the wire unconnected when someone doesn’t need the fan and to keep it connected when someone does need some wind. In summary, the switch works to either connect or disconnect the circuit between the power supply box and the fan’s motor.

Back to my problem. I have to get up from my comfortable position to walk to the switch everytime. I go to the market and return with a remote control and an infrared sensor. The sensor is to be used on the same wire which runs between the supply box and the fan. Inside the sensor is a mechanism similar to that of the switchboard switch, which is to connect and disconnect the circuit. Based on the button pressed, ON or OFF, the remote sends a message to the sensor to control the connection and disconnection. Okay problem solved. I can stay seated and control the fan!

What if I take it a step higher? I could install a voice controlled receiver which responds to the words, “ON” and “OFF”. Based on the voice input, the voice receiver operates an internal switch that connects or disconnects the fan’s circuit.

As you can see, we spoke about three ways to operate a ceiling fan using different input methods. A traditional two-way switch that you need to operate by walking to a switchboard, a remote control with ON and OFF buttons that speaks to a sensor attached to the fan’s circuit and finally a voice controlled receiver that can recognise an “ON” and an “OFF” command. You can think of other ways too. A camera which can recognise a “thumbs up” and “thumbs down” gesture for instance. So long as the underlying mechanism involves connecting and disconnecting the wires between the supply box and the fan, any way to switch the fan ON and OFF can technically work.

Internet services like Facebook and Twitter are like the circuit between the supply box and the ceiling fan. Just like that circuit understands and acts upon the instruction to connect or disconnect, Internet services understand a set of instructions which they publish for the world to use. These instructions are mostly in HTTP calls to a web server. So long as an app uses the published instructions to use the Internet service, it does not matter which app uses it and how many apps use it. The instructions will always work as advertised.

Using the instructions from an app to a service is called an API call, as if the app calls out to the service to do something. We can say that a switchboard switch, a remote control with sensor and a voice recognition with sensor calls out to the ceiling fan circuit to connect and disconnect the power supply to the fan.

Now that we know what APIs are, we can look at some of their desirable virtues.

Idempotency

This is just a fancy term for saying that the execution of API calls should be consistent even if accessed by multiple apps at the same time and should behave in a way that the user expects them to. Let us take our ceiling fan example again. If we were to use all three inputs to switch the fan on & off, then there might be some confusion. Say for instance, I set the position of the switchboard switch to ON. The fan turns on. Then I use the remote control’s OFF switch to switch off the fan. The fan turns off. Now there is clear mismatch between the switchboard switch’s ON position and the fan being off. This happened because the switch never got a feedback from the system that the fan has been turned off. The switch is now shows a state that the system is not in. This is conflict, the opposite of idempotency.

The alternative is to modify the switchboard and have two buttons instead of one switch. There should a fan OFF and a fan ON button. This will make the interfaces on all three input systems consistent. The switchboard and the remote both have ON and OFF buttons and the voice system can recognise both ON and OFF commands. The system needs to ensure that if the same instruction is given repeatedly in a series, then all except the first one need to be ignored. E.g. if I switch the fan on using my remote control’s ON button, then also press the switchboard’s ON button and finally say the word “ON”, the fan would turn on with the remote control instruction itself and the other two instructions will be ignored since the fan is already ON.

Similarly idempotency in APIs makes sure that the calls behave exactly as advertised every single time, regardless of which app is making the call and how many times the call is made. Idempotency is extremely important for apps such as bank transactions where there may be failed or duplicate instructions. Any such instruction should be dealt with correctly.

State awareness

In the above example, the same instructions from all three input systems led to ignored instructions. Ignored instructions are a waste of effort. What if we can make every instruction lead to a result? The way we can do this is to replace the two instructions on every input device with a single one. So we replace “ON” and “OFF”, with a single one called “POWER”. The switchboard has a single button called “FAN POWER”. Ditto with the remote control. The voice control system responds to only one command “POWER”. This makes sure that every POWER instruction is executed. So if we hit the POWER button on the remote, followed by the one on the switchboard and finally speak out “POWER”, the fan will turn on, then off and back on. There are no wasted instructions, because the onus of remembering the state of the system was removed from the user’s interface. Instead, the system took the responsibility. This also led to the number of possible instructions from two to one, which itself is a streamlining process.

APIs are desired to behave in similar fashion, where the service should be aware of the state of the system. The number of possible instructions is reduced since a single instruction can make the system think through the state of the system and act accordingly. This makes life easier for everyone.

Fail gracefully

What happens if there is a power failure at your home and you try to switch on the fan? The switchboard switch is no good here. You can keep pressing the switch and the fan wouldn’t turn on. There is no feedback to tell you that there is power outage. After trying the switch a few times you may check your power supply box and realise that you have no power. Then you can call your utility company to verify or get support.

But the remote control sensor and the voice sensor can be made a little bit smarter. They can have a backup battery which will take over when the main power is lost. The battery can power a small module which will speak out to the user that there is a power outage whenever the user tries to use the remote control or speak a voice command. The system lets the user know what went wrong by giving him/her proper feedback. This is an example of graceful failure. The user knows what went wrong and how he/she can expect the system to resume working correctly again.

APIs are expected to fail gracefully too. Instead of the web server crashing due to errors, the errors should be trapped and the API caller should know what went wrong along with instructions on how to set things right if the caller can. If it is a service problem, the instructions can be given on when the service can be expected to resume functioning normally or how to contact support.

Security

A ceiling fan is a very simple example and is something that anyone should be able to operate. But what if the product in question is a safe? Opening and closing a safe shouldn’t be a simple job with a single press of a POWER button. Rather, one should get the confidence that only a pre-authorised person should be able to open the safe. Hence we add other checks such as digit buttons to the front panel of the safe and also to the remote control. The safe should open only when the right numeric combination is keyed in.

APIs are also similar. If there is no authentication and authorisation, then anyone can get to anyone else’s data and create havoc. Hence APIs are guarded with authentication techniques and authorisation rights. OAuth is used commonly for such purposes. Furthermore, guarded APIs always send data through HTTPS instead of HTTP, so that no one can snoop the data passing between the service and apps.

Conclusion

Using a simple example of a ceiling fan, this post explained how API calls are the blood flow between user-facing apps and the corresponding services. Without APIs, it is not possible to create the interconnected Internet that we now love and use. In the next post, we will see what an API needs to do to qualify as a REST API.