Tech Talk: What is an API?

There’s one question we ask everyone when they interview at Particle Health: what’s an API? 

The answer to what an API does seems pretty obvious, at first glance. But even some engineers misunderstand what an API actually is. 

Luckily for you—engineer or not—I’ll be offering a high level technical overview, so you can better understand both what Particle is, and what our API does. 

What is an API:

A lot of people get scared when they hear “API” imagining a grand and endlessly convoluted computing concept, but APIs are actually very simple. An API is nothing more than a set of rules for how two systems communicate. These rules specify a set of requests that can be sent and a set of responses that can be sent back for each request. Of course, the specific rules defined and how this communication happens are where the complexity lies, but in order to understand what an API is, this is quite literally all you need to know.

You’ve probably correctly identified that this is a very general definition but this is completely intentional. In fact the power of APIs comes from their ability to be used in almost any situation. An API can be used for communication by two separate pieces of code within a single program, separate programs running on a single computer, or even totally separate computers halfway around the world from each other. Remember, an API is just defining the rules of communication—not how communication happens—so we’re not tied to a specific application of those rules.

The application that we’ll be focusing on today is using APIs to facilitate communication between separate computers. Specifically, communication between Particle Health servers and customer owned systems.

A few more key definitions before we get crazy:

A server is a computer that has been programmed to receive requests and send responses by implementing an API. Implementing an API means that the computer has been programmed to communicate using the rules defined by the API. Servers do not know how to exchange information until told how to through a program that implements the API.

A client is a computer that has been programmed to send requests to and receive responses from a server. Once again, the API tells the programmer of the client what the rules of communication are. When a computer is programmed to communicate via an API in the role of a client, this is called programming against the API.

It’s important to understand here that an API is neither a server nor a client. Similarly, a server is neither an API nor is a client an API. The API is merely the blueprint for how a server and client can speak to each other. Also note that whether a computer is a client or a server is determined based on its relationship to an API, so a computer could be a server with respect to one API but a client with respect to another. In fact, this is almost always the case.

Server vs. Client vs. API → IRL 

To help illustrate the different applications that APIs have for facilitating communication and the differences between a client, server, and API, let’s consider the example of sending a message to a coworker using Slack:

When you type and send a message to your coworker, that message is sent by the Slack client on your computer to the Slack server via the communication rules outlined by an API. The Slack server then functions as a client with respect to another API to send that message to your coworker’s computer. Your coworker’s Slack client then uses an API to tell MacOS to display a notification on your coworker’s computer, communicating within your coworker’s computer.