What's an API?

I was doing development for months, working with APIs all the time, but still didn't really understand them. I mean, I knew that I would do stuff with the Google Maps API or the Facebook API, and it would help me connect with Google Maps or Facebook, but I couldn't have really given a definition of an API or understood how to bulid one. And the more I learned about software development, the more confused I became about APIs. I started to notice that different versions of Android were all associated with different API levels, that iOS developers would talk about using an API to interact with their own servers--APIs were ubiquitous, and they clearly went beyond my limited conception of these things big companies made so you could get some cool data.

Quick and Dirty Answer I Wish Someone Had Told Me

An API is just a way to interact with an application. The same as how your keyboard and mouse are ways that you interact with your computer: you click and tap and your computer takes some actions. You do certain things with an API, and it'll do things in the application, e.g., make some data, send you some data, whatever the creators decide you are allowed to do.

For most of the APIs we talk about, the "action" that we take is going to a URL. So, we go to one URL and we get a bunch of data, we go to another URL and it makes some data for us, we go to a different URL and it deletes some data for us.

There are public APIs that people use, like MailChimp or Rotten Tomatoes. A (simplified, made-up) API call we would make to Rotten Tomatoes might look like: http://api.rottentomatoes.com/search=Batman and then, boom, the API sends us a list of movies about Batman.

But, we also make APIs for ourselves, like when we are working on iPhone apps. It works exactly the same way, but we get to control what URL we are going to and what those URLs do. So, we could make an API at http://bayleeiscool.com that understands the command "random_baylee_fact". Then if you were to go to http://bayleeiscool.com/random_baylee_fact the API would send you back a random fact about Baylee.

Yeti is a Django shop, so when we make APIs for ourselves they are in Django. It works very similarly to when we make a basic brochure website. In a simple website, you go to a certain URL, and the Django application gives you back some pretty HTML and CSS. When we make an iPhone app, we go to a certain URL and the Django application gives you back some ugly data that the iPhone does stuff with. But the basic premise is the same: go to URL, Django does stuff, Django sends you back some stuff.

Thinking about it that way, every website you go to is using an API. When you go to a URL in your browser, like google.com, you're taking an action (going to the URL), that sends a command, that loads the the Google search page.

A Little More

An API is just an "application programming interface", which is pretty vague, which is part of why understanding APIs can be confusing. My quick and dirty answer only talked about web APIs, which you interact with through URLs. But there are plenty of other types of APIs. For example, each version of Android is really a collection of APIs, there is an API to allow C developers to talk to Python code, there are APIs that allow Java and C to talk to SQL databases, etc. An API is just a programmatic way to interface with something.

When dealing with web APIs, a few concepts / phrases come up often which I want to throw down some defitions for while on the subject:

• endpoint: an API endpoint is just a specific URL and HTTP method that controls an API. It is one of the URL "actions" that we talked about above
• client: something that uses an API. When you go to Google Maps on your computer, your browser is a client of the Maps API. When you use the Google Maps app on your phone, that app is a client. When you use some other service on the internet that uses Google Maps, that service is a client.