What is an API? A Simple Guide for Non-Techies

Once upon a time, before a pandemic took over the world, there was a daily opportunity for cross-departmental engagement: lunch time.

Back then, team members from various departments could gather and walk to a nearby restaurant. Maybe they would chat about the latest episode of their favorite TV shows or discuss a recent sports event unencumbered by the muffling of a mask. Remember?

This was also an ideal time to ask your developer colleague that burning question: “What IS an API?”

In this teachable moment, you developer colleague would likely leverage the situation and use a classic example, explaining that, when the waiter stopped by your lunch table to deliver the menus, the waiter is essential representing an API.

What Is an API?

The restaurant analogy has been used to explain APIs for roughly a decade, and for good reason: It makes more sense than answering “What is an API?” with the unhelpful “Application Programming Interface.” Yes. That’s what it stands for, but that doesn’t help explain what it actually is or what it does. So, let’s head back to the restaurant and use that analogy.

In this scenario:

• You are the API customer: The one sending a request for service or data.
  
  
• Your waiter is the API: The data messenger and delivery mechanism for, in this example, your delicious French onion soup. You can’t go into the kitchen and order directly from the chef. You have to send a request through the waiter. The waiter transports the request (extra croutons, please!) from you to kitchen, then transports the data or service (your lunch) from the kitchen to you.
  
  
• The menu is the documentation: It tells you what you can ask of the API, your waiter.
  
  
• The kitchen is the API server: It supplies the service or data, yet it only has certain sets of data, just like if you go to a vegan restaurant, you can’t ask for a meat dish. It won’t be on the menu, or in the case of the API server, the documentation. If you try to order it anyway, you’ll get an error code, because the kitchen can’t deliver it.
  
  
• Then there are the secret ingredients: You can get certain datasets, like an answer to whether a dish includes onion (it’s French onion soup, so yes). However, you won’t be able to discover the secret ingredients that make this restaurants’ soup unique here. You also won’t be able to get the chef’s home address. The kitchen, as the API server, will serve you while maintaining confidentiality, security, and compliance.

How APIs are Used in Application Integrations:
A Simple Example

Every once in a while, you probably sign up for a new app or piece of software. For this, you usually need to create a new user account. There’s likely a form with multiple fillable fields, but to save you trouble, the app might suggest you use your Facebook credentials to login. And with the click of a button, you’re in! Magic? Nope. API.

In this scenario:

• The new app is the API customer: It’s the one requesting service from Facebook, saying, “Hey, let me verify this person’s identity and grab basic information, like her name.”
  
  
• The API allows the communication between Facebook and the new app: It transfers the new app’s request to Facebook, and grants the ability for the app to sign you up quickly.
• Facebook has developed documentation: In this case, it’s clarifying what can be integrated and shared, what can’t, and under which conditions.
  
  
• Facebook is the API server: It provides the data-based service, which is to help the app sign you up quickly.
  
  
• There are secret ingredients here, too: Facebook won’t share all your data, like your password, with the new app. Facebook will only share what was determined in its documentation.

Let’s look at two of the key API types: REST API and real-time API. What’s the difference?

REST APIs

You might be thinking, a REST API has to be what you do after the team lunch, right? A French onion soup-induced nap?

That would make sense, but actually, a REST API is what happens during lunch. It’s “restful” because it’s a relatively simple operation. Basically, REST stands for Representational State Transfer. That means that a server responds to four types of requests:

• Create: a new element in the code, such as adding a new user. Think of a team member that got delayed at the office and is joining you mid-lunch. To accommodate, the waiter must bring an extra chair.
• Read: the information that is available but only if requested. This is like today’s lunch special – something that isn’t on the set menu that you always have to ask your waiter about.
• Update: the code, say, when you request something be modified. So here, this would be like asking your waiter to add more cheese once your soup arrives. Because… cheese.
• Delete: removal of items from the code. So, even though you ordered it, you decide to skip the cheesecake because by now, you may be a little over-cheesed and you still need to get back to work. You ask the waiter to delete it from the order’s code.

Real-Time APIs

Think of that time you ordered a taxi instead of walking to a restaurant, and saw the taxi’s progression toward your office across a map. A real-time API transfers data from its server (here, Google Maps and GPS) to the destination app (your taxi provider) every 100 milliseconds or less.

Browsing a site while waiting for the taxi? Searching for lunch deals? A website could integrate real-time promotions from multiple restaurant servers through APIs. Therefore, every time a promotion gets offered in any of the restaurants’ apps, it will automatically show up on this one site that you’re checking.

Applications are Better Together

Ultimately, the best way to understand APIs is to view them as communication between two applications. Just like in human communication, applications need to speak the same language and ensure clarity.

We’ve all been in situations where we said one thing (sent an API request), and the other person (the API server) heard something else entirely. That’s why apps have documentation.
And like in other healthy relationships, applications have boundaries, which protect their customers’ data.

Ultimately, it’s our ability to rely on each other’s strengths and lift each other up that make this world better (plus, French onion soup. Yum!). An API helps apps do the same.