6 min read

What is an API?

What is an API?

The textbook response

APIs have been a hot topic in technology for years.

API stands for Application Programming Interface. The technical definition of an API is any uniform interface that can be accessed by multiple software applications.

Sometimes the textbook answer doesn't actually describe how we work with these things.

It sounds more complicated than it really comes down to when you think about the actual use case - which may simply involve one app accessing data from another program with parameters or arguments passed through.

Behind the scenes

An API is a group of logic that takes a specific input and gives you a specific output. A few examples:

  • If you give the Twitters API you can make a request(input) to Twitter to give you back 500,000 tweets per month with these parameters as output
  • If you give the Javascript Array.Sort API a group of numbers as an input, it sorts those numbers as an output
  • If you give the Lyft Driver API a start and finish address as an input, it finds the best driver as an output (I’m guessing)

For most people, an API is a resource you can leverage to retrieve, create, update or delete data.

APIs are like a toolbox for building modules of code.

When engineers create these "modules" to do specific things, they clearly define what input those APIs take and produce an output based on that request: it’s all really quite simple!

APIs can be called in much the same way you call your Nana(that’s what my daughter calls grandma).

When Nana needs help fixing her Apple TV, she’ll make a call(aka a request) to someone techie(like you) and you respond with an answer(aka response)

Inputs

An API will usually tell you exactly what kind of input it takes. If you tried putting your name into the Google Maps API as an input, that wouldn’t work very well; it’s designed to do a very specific task (translate address to coordinates) and henceforth it only works with very specific types of data. Some APIs will get really into the weeds on inputs, and might ask you to format that address in a specific way.

Outputs

Just like with inputs, APIs give you really specific outputs. Assuming you give the Google Maps API the right input (an address), it will always give you back coordinates in the exact same format. There’s also very specific error handling: if the API can’t find coordinates for the address you put it, it will tell you exactly why.

🛑 Hold Up! We missing something 🛑
It’s hard to separate anything that talks about APIs from how you actually call those APIs: we’ll cover the architecture of APIs (REST, gRPC, HTTP requests) in some other posts.

Your favorite apps are just collections of APIs

If people mention, frontend or back-end they are just using fancy words for API.

Most apps you use, like Instagram or TikTok have their user interface built with something like Javascript paired with React or Angular.

Then there back-end which does the data processing piece using something like Java, Python, GoLang, Node, PHP or something similar.

The backend

Companies start by building APIs for all of the important things that users are going to need to do in their app. For Gmail, Google started with APIs that receive, show, send, and forward emails; but those are all called through code.

These APIs, and the logic for when they get used and how, is the application’s backend. It’s like what’s going on under the car hood. If you’re heard of a backend engineer, it’s a developer who’s working mostly on these internals.

The frontend

All of those backend APIs are only usable through code, which isn’t really something you want to deal with to check email on your iPhone. That’s why companies build frontends for their apps: graphical user interfaces that make apps pretty and usable without having to write code. Here’s how that works in Gmail:

  • Your inbox shows rows of emails and subject lines: the frontend is taking that backend email data and formatting it nicely
  • You can click on the star icon to flag an email: on the backend, that’s triggering a “mark email as flagged” API

Most interactions on the frontend get translated into an API call on the backend, and that’s application software 101. Once I started to understand this model, it was easier to understand how developers actually use “API” in conversation.

What’s an API in real life?

In my experience when people refer to APIs they usually fall in one of three categories. Internal APIs, Public APIs and Interfaces. They are really all the same but lets clear up the confusion.

Internal company APIs

When companies build their applications, they design them as a group of interacting APIs. The easiest example to understand is DoorDash. There are a few things you might want to do in the DoorDash app, and they all trigger different APIs behind the scenes.

This pattern holds for almost any app you use: actions that you take in the app will trigger internal company APIs that actually do the work to get your request fulfilled. Internal company APIs are also layered: even though there’s probably a broad “Order from Taco Bell” API, there are a bunch of smaller APIs under that hood that get it done: find a driver, submit order to restaurant, provide estimated time of food delivery, verify credit card, communicate with users, etc.

Public APIs

None of those DoorDash APIs are publicly available: they’re just the way that DoorDash actually provides their service to you on the backend. However, sometimes a company will make a few of their APIs available, and give you instructions on how to use them. A great example is the Twitter API.

Normally, you’d use the Twitter app, which makes a bunch of API calls to internal Twitter APIs like show feed, send reply, and search (this is what we just spoke about: frontend and backend). But you can also call those APIs yourself, with code, outside of the Twitter app. For example, there’s a get user timeline API that you can use to see a user’s timeline (their tweets) – that API returns those tweets in JSON, which is a special text format.

Now if you’re wondering ”why should I care”, it’s because these kinds of public APIs let people build apps on top of Twitter. Ever wonder how some of these people hope on twitter and have immediately growth? They are most likely using a program that connects with Twitter APIs to create, analyze and schedule tweets to boost overall engagement.

Code interfaces

The first two types of APIs that we just looked at are functional – they usually accomplish something that’s practical and easy to understand, like giving you coordinates or order food. But developers also use “API” to refer to much lower level inputs and outputs, like functions in code. (this is the type of API that took me the longest to understand)

A good example is Javascript’s array.sort() method. It’s an API that takes a list of numbers or letters as an input, and then sorts them and gives them back to you as an output. There are other APIs related to arrays, like for adding (array.push) and removing (array.pop) things, filtering (array.filter), and getting an array’s size (array.length). You use these when you’re writing in Javascript.

🚨 Wait!! Pause  🚨
It’s not always going to be clear what exactly people are talking about when APIs come up, especially because developers use the word for a ton of different things. If you’re confused, just ask! Chances are the answer will fit into one of these three categories.

Final Thoughts

APIs were always a confusing thing when I first started because I never knew if people were talking about public, private, language APIs or something else.

Over the past 5 years or so, the idea of building your application purely as a series of interacting APIs has gotten much more popular, and it's called micro-services. Another topic for another post.

Thanks for reading!