Want To Understand API’s? Read This.

Anyone who watches TV should be able to understand what an API can do for you.

Remember the first time anyone mentioned the word API to you? They probably went on to explain that it stands for ‘Application Programming Interface’. This only made things worse and left you confused.

An API is not some kind of dark magic only programmers can understand. If you have ever watched TV and used a remote, then you should be able to conceptually understand what an API allows you to do.

The remote you use to control your TV can be seen as an API.

The remote makes the actions available in the TV accessible to others.

Compare this to a simple definition of an API:

An API makes actions available in an application accessible to others.

The remote and the API both make actions available to others.

When you change a channel or adjust the volume, all the magic that makes this possible happens in the TV. We have no clue how this works and nor do we need to. If we understand what the button does, we simply press it and the TV takes care of the rest.

Ready For The Big Game

Before we can get into more detail of how an API works, let me describe a concrete situation to you.

Imagine you are all geared up to watch El Clásico on the Movistar sports channel. You sit in front of your TV with your best friends, surrounded by snacks and beer. Everybody is excited. You cannot wait to see how Barcelona will perform against Real Madrid without Neymar.

You try to change channels to the match. Nothing happens. It turns out that the batteries in your remote are dead. You walk to the TV and try to find the change channel button. You have one of those fancy superslim TV’s that turns out to only have a single button: on/off. What happened to the good old days where the all TV’s had controls on the outside?

All stores are closed, so changing the batteries is out of the question. What now? Is there any way you can still watch the match together with your friends?

API To The Rescue!

Luckily you have a smart TV that has a well-documented API that allows you to communicate with your TV. As you have learned from the definition, the API makes actions on the TV available to you.

You think long and hard, and draw the conclusion you only need to know two things:

1. What TV channel is the game on?
2. How do I change the TV channel to the channel of the match.

You open your laptop and look through the online documentation. You find the relevant API endpoint to list all available channels with information about each station:

http://smart.tv/api/channels.list

Wait, But What Is An API Endpoint Exactly?

An API endpoint is the same as the button on a remote. Press a different button and you get a different result. Access a different endpoint, and you get a different result as well. By going through the documentation of the endpoints, you know which ‘buttons’ are available in the API.

Except that in an API you do not press a button, but you perform a request. A request is nothing else but a fancy word for sending a message. So instead of pushing a button to change the volume, in an API you would send a message to ask the application to change the volume.

API endpoints are more picky than the buttons of a remote control though. You need to format the message you send in exactly the right way, so it understands what you want to do. The message you send, and not only the endpoint, may also affect what you receive back. This is all described in the documentation.

Back To The Channels.List Endpoint

The first part of the channels.list endpoint: http://smart.tv/api/ is where the API is available to be accessed. This is where the API of the TV listens for any requests that come it’s way.

The second part, channels.list, is the endpoint, which determines what kind of actions are available and what kind of messages it expects to receive.

So you open http://smart.tv/api/channels.list in your browser window, which results in sending of the request to the API. The API sends the following response back (shortened to display only two channels, instead of all):

Channels.list response:

{"channels": [{"channel number": "8","channel name": "MTV","program": "Jersey Shore","language": "en_US"},{"channel number": "9","channel name": "Movistar","program": "El Clásico","language": "es_ES"}]}

So now you know that the game takes place on channel 9 of your TV! All you need to do now is to change the channel of your TV to 9. This is easier said than done.

Changing Channels

Luckily there is an API call available that allows you to change the channel to a specific number:

http://smart.tv/api/channels.change/?chn=

This API call is more complicated than the previous point. Apart from having an endpoint, channels.change, it allows you to send a parameter as well, chn. The parameter determines the channel you want to change to.

You change the parameter of channel to 9 and perform the request:

http://smart.tv/api/channels.change/?chn=9

The API sends the following response back:

{

  Status: “OK”

}

You see the channel successfully changing to channel 9 and everybody starts cheering. You are now able to watch the game!

Generally speaking, API’s only support two different things:

1. To get information from the application of interest. For example, to find out the current system time of the TV.
2. To perform an action in the application of interest. For example, to change the volume.

With an API, your application can easily communicate with other applications. An API opens the door for other people to build exciting applications on top of what you have already built.

Congratulations, You Now Have A Basic Understanding of API’s!

Based on just these two API calls, we could very easily build a mobile app that shows all the TV channels that are available and would allow you to change the channel using just your phone. We would just need to build an app that makes the right requests to the API.

Now imagine if your TV did not have an API. There would have been no way to access the TV without using the remote. This is the power of an API. You make information and logic from your application available to easily be used by others.