ELI5: What is an API?

Andrew (he/him) - Mar 18 '19 - - Dev Community

API is a term that's thrown around a lot by programmers and web developers but it may be foreign to newbies. What exactly is an API? What does API stand for? How are APIs used?

The Basics

API stands for Application Programming Interface, which is best understood by rearranging those words a bit: an API is an interface which helps you program applications more easily. An API is a bit of code (maybe a lot of code) that someone else has written previously, which makes your job a lot easier -- you can reuse their code instead of reinventing the wheel.

A good example is a photo-editing smartphone app. If you want the user to be able to take photos, edit them, and save them to their phone, there are a lot of steps that you would like to be able to skip. For instance, you don't want to have to interpret the hardware information coming from the camera, or allocate memory for the edited photos, do you? The people who wrote the API for the smartphone have already written code that lets you do these things easily. You can just open the camera's API and instruct it to return the next photo the user takes to your program as a *.jpeg file, or save the edited file using a saveFile() method in the smartphone's filesystem API.

In other words, "API" is just another name for someone else's code.

Encapsulation

Like a set of LEGOs, a good API gives you all the building blocks you need to create anything you want. Just plug the components together in the correct order and you're good to go. Of course, the API itself can restrict what you can build. You can't make a life-size Tesla out of LEGO if all you have are 1x1 clear blocks. The API necessarily restricts you to working on a particular kind of problem (or jerry-rigging an abomination of a solution to a totally unrelated problem).

Additionally, an API is a black box -- you usually don't know what's going on between making the call to a particular method in an API and receiving the return value, unless you have access to the source code. If I call the charAt() method on a Java String, there's nothing in the API documentation that tells me what's going on behind the scenes, although the API does give me useful information like the return type of the method, as well as any Exceptions which might be thrown. While this may seem like a disadvantage at first, it's actually a very useful feature. Encapsulating the behaviour like this encourages following the Law of Demeter, and it also means that whenever the API is updated, any applications which rely on that API will immediately inherit those improvements (or crash dramatically a la left-pad).

APIs are Everywhere

Whenever code written by one person or group tries to interact with code written by another person or group, that interaction takes place via one or more APIs. The filesystem on your personal computer has an API which is accessed by programs when they open, edit, and save files. Google, Facebook, Twitter, and other companies have web APIs which you can use to programmatically access data and search results. Programming languages themselves have APIs which define how to use those languages to build more complex APIs.

Ultimately, API is an umbrella term which shouldn't scare away anyone new to programming. It's just a way of saying "all the code which is meant to help you perform a task". It's code that has been written and tested and used by lots of other people, which you can use to help build your own applications.

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .