When you use language to ask a question from someone, you are using a set of rules that are hidden from you. Over the years, your brain learnt how to form correct syntax without anyone explicitly explaining the rules of those syntax. You expect a response from the listener because you believe that they can decode your message to understand the meaning. But if you use jibberish or incorrect rules, the listener would be confused and you won’t get any response from them.

Similarly, software talk to each other using some rules. In fancy terms, this is called as Application Programming Interface (API). But these rules are explicit and are created by designers of the API. If you hang out on tech websites, you will come across mentions of Twitter API, Facebook API or Google API. By creating these APIs, the companies are telling developers (mostly working outside of these companies) that if they want to talk to them, they better form their messages in a specific way. Why not simply use http://www.twitter.com to talk to them? Because that is a URL that provides an HTML page. That page doesn’t contain data in raw form. If you are a developer and you want to build extensions or apps on top of Twitter or Facebook, you are more interested in the raw data. And that’s where their API comes in.

As an example, let’s look at an API of one of my favorite places on the internet - Hacker News (HN). If I wanted to create an alternative version of this simplistic website with some fancy design and additional functions, I would want an easy way to get the raw data present on this website. I could extract data from HTML pages using jquery or javascript but that’s rather tedious and doesn’t allow me to quickly access multiple “resources” available on HN like users, comments, best stories.

Since HN developers want their website to be popular, it’s in their interest to encourage alternative designs of their website (a.k.a clones). Therefore, we have a Hacker News API for developers to access the raw data and build enhancements on top of HN.

Following is the root link to access the API: https://hacker-news.firebaseio.com/v0/

Now if a programmer wanted to get raw data for top stories on HN, they would send a “GET” request for: https://hacker-news.firebaseio.com/v0/topstories.json

Go ahead and click that link. It will give a list of ids for all the top stories, like so:


Of course your list of numbers would be different because top stories are always changing. But what can you do with these numbers? You can use them to access info about a specific story. Let’s say I want to know more about the first id in that list 15589191, I would send a GET request for the link https://hacker-news.firebaseio.com/v0/item/15589191.json. Following will be the result:

  "by" : "Mz",
  "descendants" : 10,
  "id" : 15589191,
  "kids" : [ 15589589, 15589616, 15590055, 15589337, 15589969 ],
  "score" : 80,
  "time" : 1509399932,
  "title" : "The 'Manhattan of the Desert': Shibam, Yemen's Ancient Skyscraper City",
  "type" : "story",
  "url" : "https://www.archdaily.com/771154/the-manhattan-of-the-desert-shibam-yemens-ancient-skyscraper-city"

This is a JSON way of storing information (bunch of key-value pairs) and it makes it easier for developers to extract specific info using their favorite programming language. The type key in that JSON tells us that it’s a story. Do you see the “kids” key in that output? That contains a list of ids that represent all the comments on that story. You can change the above link by replacing 15589191.json with one of the kid 1558616.json to get one of the comments posted on that story:

  "by" : "bdamm",
  "id" : 15589616,
  "kids" : [ 15590104, 15590092 ],
  "parent" : 15589191,
  "text" : "It would be interesting to learn how the builders decided on these specific structures. I note a few attributes:\n* Banked foundations.\n* Small windows at the bottom, large windows at the top.\n* Tall doors at the bottom.<p>Specifically, how did they gauge the thickness of the walls and the structural properties of the mud? Was the planning based on a published code that took into account the expected building materials? Did they have occupancy limits?",
  "time" : 1509403246,
  "type" : "comment"

Again, the type quickly tells us that it’s a comment. Furthermore, this comment has its own “kids” key that contains ids representing comments that replied to this it. It even has a parent key to identify the original story that we saw above. All this content in JSON format will help a programmer who is trying to redesign Hacker News to give it more wings and make it more beautiful.

HN API is quite simple but some APIs are quite complex with rules for even authenticating a user. Using such APIs, you don’t only GET the data from a website, but can also POST the data to update the website. An example of this would be posting a tweet to Twitter from command line without ever going to twitter.com on your browser. Programmers like to stay in Unix shell to access websites so it is not surprising that a developer did just that using the Twitter API and created a program t to access most of Twitter’s functionalities without ever leaving the Unix shell.

These “Web API’s” are only a particular type of APIs. There are APIs for programmers who want to talk to Operating Systems and create desktop applciations. There are Hardware APIs that allow programmers to build programs that talk to that hardware. A comprehensive list can be found here. Weather APIs are a popular example because they are regularly used by programmers to create weather apps.

So a simple definition would be: APIs are a set of rules created for programmers so that they can create a computer program that can methodically talk to an existing piece of hardware or software.