A Non-Tech Introduction: APIs

30 September 2014

This non-tech introduction covers the topic of application programming interfaces, or APIs. This is another one of those concepts that non-tech people might never need to deal with, but one that underlies a lot of how the modern internet works.

As the internet grows, one thing might not be immediately obvious to users like you and me: not only are people becoming more and more interconnected, but so are the web products that we use (web products include almost any kind of app or website you can think of on the internet). In today's internet, users take this almost as given, and we might not even consciously register examples of how one web product uses another. For example, Yelp restaurant pages use Google Maps to power the mini-map, and checking in on Foursquare allows us to seamlessly post that check-in on our Facebook feeds as well. These kinds of cross-product interactions are generally handled by APIs.

What is an API?

An API is a way to communicate with a web product (a much more technical definition can be found here, and the term is a bit more general than what I'm saying here, but bear with me).

This seems like a trivial thing to do, because we as users communicate with web products all the time. For example, I can ask Facebook for the profile page of a friend by just searching for and clicking on them on the Facebook website. However, what if I had my own web product where I wanted to write code that allows me to automatically get information from a user's Facebook page?

I could theoretically write some code that would mimic the information gathering process that I as a human go through: the code could pop open a browser, navigate to the target's page via the search bar, and then "look" at that page to see what's on there. But, this is a very messy process that's not straightforward to do with certain websites.

That's why many web products will have APIs. These are usually special URLs that you can access, where you can ask for specific information from the web product. If you accessed the API correctly, the web product will then respond with the data you want in a very clean format (for the more techy inclined, this format is usually JSON).

How do I use an API?

There are a couple of nuances involved with using an API. For the below examples, we're going to focus on Yelp's API.

The first nuance is that a company providing an API will define exactly what kind of information you can request, and what information you will receive for each request. All of this is usually defined in the API's documentation provided by the company; for example, the documentation for Yelp's is here.

In the Business API, we see that we can ask the API for information about a specific business. In order to do so, we have to access the URL of the pattern http://api.yelp.com/v2/business/{business-name}, where {business-name} is a name unique to that business (this kind of naming convention, where each distinct entity has a unique name, and the names consist of only letters, digits, and dashes, is sometimes called naming things with "slugs"). In response, Yelp will return to you certain fields of information, such as the business's name, phone number, rating, and location. This particular API will not, for example, return all the reviews associated with that business.

Sometimes, an API might not be enough for what you're looking to do. For example, no Yelp API URL format (or "API endpoint") offers all the reviews for a given business. If I wanted to build an app that depended on that data, I would have to figure out some other way to get it.

Another nuance with APIs is that you have to tell the company who you are when you ask for information. This process, "authentication", is important for API pricing (see below), and helps the company block access from undesirable requesters (e.g. bots, for certian companies).

There are different ways an API might require you to authenticate yourself. Yelp's, for example, requires something called an OAuth, while Foursquare's API just requires you to put a code unique to you into your API URL request.

This brings us to the third nuance of using APIs. You might wonder how you "ask" the API for certain kinds of information. With Yelp's Business endpoint above, it was easy because we could just put the business's unique name in the URL. But what if you wanted to use Yelp's Search API, and you needed to supply a search query?

You can do so using a special convention in the URL. In URLs, anything after a question mark becomes what is known as a "query string", where you can pass in additional data separated by ampersands. When you visit a URL like www.test.com/city/?city_name=new-york, you are actually visiting the URL www.test.com/city and telling the website that you're giving it a variable city_name with the value new-york. If the page is set up to handle a "city_name" variable, it will then react accordingly with the request.

Bringing it back to Yelp, the documentation has the example API URL of http://api.yelp.com/v2/search?term=food&location=San+Francisco. There, you are declaring that a) you want to use the Search API, b) you want the search to be for the term "food", and c) you want the location to be "San Francisco". With the Foursquare API mentioned above, you put your special access token as one of these parameters in the URL, in addition to any other variables needed for the API to work.

APIs can be very powerful, however, and might take unexpected forms. For example, when you visit a Yelp restaurant page, you'll see a map of the business. That map is actually powered by Google Maps, and is retrieved via the Google Maps API. This API is more complex to use, but can be very powerful.

In addition, APIs can also be used to give a web product information. For example, part of Facebook's API allows me to post things to my wall, or to put a "Like" button on something on my own web product.

What's the catch?

APIs are essentially a way for you to access the data held by another web product, which can be a very powerful thing to have when you're building your own web product.

However, companies generally charge for access to their APIs; this data doesn't come cheap! You usually get charged for access to an API based on each request you make to it. What's nice, however, is that companies will usually give you a certain number of free requests per day, which can be very useful if you're just starting off or working on a small side project.

If you hit the free limit, the data source will cut you off ("rate limit" you). Companies that make many thousands, or millions+, requests, will work out their rates with the data source - imagine how much Yelp is paying Google Maps for all those map API calls! To give a sense of scale, the Google Maps API gives 25,000 free requests a day, and then every 1,000 requests after that costs 50 cents.

The good news is that data sources, especially the biggest ones, are generally incentivized to provide fairly high free limits to their API, since they want to encourage developers to use their data when building out new apps for that ecosystem. This is why, for example, Yelp recently raised its free API limit by a lot.


APIs aren't a very prominent feature to those outside the tech world, but they can very quickly help you juice up a side project. Plus, it's useful to understand how the internet works, and APIs are absolutely vital to how quickly the modern internet has grown.


comments powered by Disqus