What Really is an API?

I could tell you API stands for Application Programming Interface, but you probably know that already. So, what really is an API?

Let me explain APIs to you with an analogy of what happens when you order pizza.

High-level Pizza API

Say you’re having friends over for movie night so you decide to order a box of pizza to share with them. The process of placing and receiving your order may go as follows:

1. You call the pizza vendor and tell them the details of your order. These might include your home address and what spices you’d like on your pizza.

2. The vendor verifies your order and tells you how soon they can deliver a box of pizza to you.

3. You sit back and wait for the pizza delivery person.

4. Your doorbell rings, you answer the door, receive your order and pay the delivery person.

Mission accomplished, right?

Well, you forgot to tip the delivery person but that’s a discussion for another day.

The important point in the above transaction is that you ordered and received a box of pizza without knowing specific details such as:

• how the pizza was cooked

• what materials were used to fabricate its wrappings, or;

• what route the delivery person took

Similar to how you can order pizza without knowing exactly how it is prepared, APIs allow you to programmatically perform complex operations without knowing the exact details of each step of the operation. It’s like knowing the light in your bedroom will come on when you flip the light switch without knowing exactly why the switch can turn on the light.

Examples

For example, the Document Object Model (DOM) is an API which defines and manages the logical structure of HTML and XML documents. It provides an easily accessible programming interface for element/node creation, modification, and removal on a web page

The document object in JavaScript provides a simple interface which programmers use to access and manipulate DOM elements without having low-level knowledge of how the browser performs such operations.

document.querySelector(‘.list-item’).remove(), for example is a chain of document methods which remove the first element of the .list-item class from the DOM of a web page. A regular JavaScript developer who writes this command knows:

• document is an object representing the HTML document

• querySelector(CSS-selectors) is a document method which selects the DOM element matching the CSS-selectors passed as the method’s arguments.

• calling the remove() method on an already selected element removes the element from the DOM.

The developer doesn’t have to understand or write the source code defining the document object or its remove or querySelector methods before using them. This sort of abstraction is what makes APIs so important in software development.

Another example of an API is the Web Animation API which provides a common language for describing and handling animated DOM elements.

Not All APIs Are REST APIs

Spending a lot of time on tech Twitter and YouTube as a newbie may have misled you into thinking all APIs must be some (third-party) web server resource. This is because:

1. Web developers are some of the most vocal/popular groups on tech Twitter; and,
2. When web developers speak of an API, they’re usually referring to REST APIs which are accessible through web server endpoints. However, if you’ve been paying attention, you will notice the Web Animation and DOM APIs mentioned above are not server resources. They’re built into web browsers. In fact, MDN has compiled a large collection of web (not necessarily REST) APIs used in web browsers. So, not all APIs are REST APIs. Still, REST APIs are some of the most used APIs today. OpenWeather API, for example, provides a REST API for retrieving weather forecasts in JSON, XML, or HTML format. Going back to the pizza example from earlier, if a developer wishes to order the weather forecast of a given city, the developer needs to:
3. procure an API key which provides access to OpenWeather API’s weather information
4. specify relevant parameters (longitude/latitude or city name and API key) in the API endpoint’s URL
5. initiate a HTTP GET request to that URL and receive the desired weather forecast. The developer doesn’t need to have deep knowledge of meteorology, have access to a meteorology satellite, or learn how to operate such a satellite before retrieving weather forecasts from the API. I hope you find this post helpful. Also, I probably didn’t cover all aspects of APIs which may shine more light on the subject. So, please leave your contributions and questions in the comments.

Further Reading

• API by MDN
• REST by MDN
• Abstraction by Computer Science Wiki

The cover image in this article was provided by Gerd Altmann from Pixabay