What is an API?

I’m typically involved in web UI and backend service development projects that expose endpoints via HTTP or other network protocols. Over the years, I’ve seen people throw around the term API when referring specifically to Web APIs - in other words, web services. In most cases, this is innocuous, but I’ve come to learn that for some, it’s hard to differentiate or even define what an API is, let alone understand the differences between Web APIs and other types of APIs! This article is intended to be a resource to explain it in my own way.

First, let’s expand the acronym: API stands for Application Programming Interface.

Interface

I think “application programming” is pretty self-explanatory (or at least self-researchable), so I’ll focus on the “interface” part first. A basic definition of an interface is something like: “a point where two systems, subjects, organizations, etc., meet and interact.” This is quite easy to understand when it comes to graphical user interfaces (GUIs). It’s what most of us interact with on our personal computing devices like smartphones and laptops - think of Windows, your Android/iPhone device, the apps that come with them, and how you interact with them.

Another example for the more technically minded is a command-line interface (CLI). Using your command-line application (or shell) of choice, you can interact with an application. Instead of a graphical user interface, you’re using its command-line interface. See where this is going?

Back to APIs

Okay, so we understand a bit more about interfaces and have some examples. Let’s discuss application programming interfaces. These are interfaces that allow applications to communicate with one another. You program an application to communicate with another application through the application programming interface, or API, that it exposes. That’s it! There’s no mention of a protocol because it’s not necessary. Think about an SDK you use to, for example, leverage your host operating system (OS) to read a file from disk. You might do something like:

  System.IO.File.ReadAllBytes(pathToFile);

When your code leverages the host operating system (OS) to read a file from the disk, it’s communicating with an API exposed by that OS to make that communication simpler. This is still an API.

Web APIs

Web APIs are the same thing: you program your application to interact with another application through its API, except this time it’s exposed over the Web (or at least, over a network). Most commonly, this happens over the HTTP(S) protocol (though I’m increasingly seeing gRPC gaining favor). It involves serializing data to send to the target application and deserializing the data received in the response.

You may also hear the term REST (REpresentational State Transfer) API thrown around. Now, RESTful APIs are meant to adhere to a specific set of principles, but I’ve seen this term also used loosely. In some cases, people refer to any Web API that communicates using JSON as a REST API. This is simply false (you can use XML or even SOAP to define RESTful APIs), but it’s good to know what people might mean when discussing web services.

Conclusion

I hope this helps people define and disambiguate these terms in their future discussions. Using a common language to discuss complex topics helps everyone understand the situation much more easily, allowing for deeper dives into more complex subjects. Your words and what they mean are important and impactful!