December 19, 2016

How to Use an API: Just the Basics

Written by

I used to work in customer support at a technology company where API connections that pulled user data from other programs were integral to the product. When I would explain to customers why we couldn’t access a particular piece of data, developers would often recommend the answer, “It’s not available over the API.”

At the time, I figured an API was like a USB port, and by connecting to that port, we would have access to everything in another program. Turns out, I was wrong.

ALSO READ: Zapier vs. IFTTT: The Best Tool for Task Automation

APIs are less like USB ports or fire hoses than they are like a person at a help desk in a foreign country. An API will not give you all of a program’s information or code (like a fire hose), because what would stop you from replicating the entire code base? Instead, an API provides you with data its programmers have made available to outside users. Even so, you have to know the language and ask the right questions in order to do anything with this data.

What is an  API?

API stands for application programming interface. The most important part of this name is “interface,” because an API essentially talks to a program for you. You still need to know the language to communicate with the program, but without an API, you won’t get far.

When programmers decide to make some of their data available to the public, they “expose endpoints,” meaning they publish a portion of the language they’ve used to build their program. Other programmers can then pull data from the application by building URLs or using HTTP clients (special programs that build the URLs for you) to request data from those endpoints.

Endpoints return text that’s meant for computers to read, so it won’t make complete sense if you don’t understand the computer code used to write it.

TL;DR: An API allows one program to request data from another.

Why You Should Use an API

Computers make a lot of things easier, especially tasks that involve collecting and sorting through tons of data. Let’s say you wanted to know how many times a particular business partner submitted invoices to your company. You could feasibly go into your company’s invoice records, scan the “from” data input, and print each invoice individually for your audit.

On the other hand, if all invoices were uploaded to a central database, you could write a simple program that accesses that database and finds all the instances of the partner’s name. This would take much less time and be much more accurate.

Architecture of an API

APIs consist of three parts:

  • User: the person who makes a request
  • Client: the computer that sends the request to the server
  • Server: the computer that responds to the request

Someone will build the server first, since it acquires and holds data. Once that server is running, programmers publish documentation, including the endpoints where specific data can be found. This documentation tells outside programmers the structure of the data on the server. An outside user can then query (or search) the data on the server, or build a program that runs searches on the database and transforms that information into a different, usable format.

That’s super confusing, so let’s use a real example: an address book.

Back in the analog days, you’d receive a copy of the White Pages phone book, which listed every person in your town by name and address, in alphabetical order. If you needed a friend’s address, you could look them up by last name, find the address, then look up their street on the maps included in the back. This was a limited amount of information, and it took a long time to access. Now, through the magic of technology, all of that information can be found in a database.

Let’s build a database containing the White Pages for a fictional town called Happyville. The folks at Happyville_WP decided that when they built their database, they would create a few categories of information with nested data underneath. These are our endpoints, and they’ll include all the information the API will release to an outside program.

Here are the endpoints listed in the documentation for Happyville_WP:

  • /names
    • /first_name, /last_name
  • /addresses
    • /street_address, /email_address/
  • /phones
    • /home_phone, /mobile_phone

Obviously, this isn’t all the information that could be collected about a person. Even if Happyville_WP collected more private information about the Happyville residents (like birthdates and social security numbers), this data wouldn’t be available to outside programmers without knowing the language of those endpoints.

These endpoints tell you the language you must use to request information from the database. Should you want a list of all of the folks in Happyville with the last name Smith, you could do one of two things:

  1. Make a URL request in a browser for that information. This uses your internet browser as the client, and you will get back a text document in coding language to sort through. That URL might look something like this: http://api.happyville_wp.com/names?last_name=smith 
  2. Use a program that requests the information and translates it into usable form. You can code your own program or use a ready-made HTTP client.

The first option is great for making simple requests with only a few responses (all of the folks in a Happyville with the last name Xarlax, for example — I’m pretty sure there are only six households with this name in Happyville). The second option requires more coding fluency, but is great for programmers who want to use the database of another program to enhance their own apps.

Many companies use the open APIs from larger companies like Google and Facebook to access data that might not otherwise be available. APIs, in this case, significantly lower the barriers to entry for smaller companies that would otherwise have to compile their own data.

Actions You Can Take Through an API

Wow. Okay, so an API is how two computers talk to each other. The server has the data and sets the language, while the client uses that language to ask for information from the server (FYI, servers do not send data without a client requesting data, but developers have found some ways around this with webhooks). APIs can do anything!

Well, not so fast. The language and syntax of APIs severely limits their abilities. There are four types of actions an API can take:

  • GET: requests data from a server — can be status or specifics (like last_name)
  • POST: sends changes from the client to the server; think of this as adding information to the server, like making a new entry
  • PUT: revises or adds to existing information
  • DELETE: deletes existing information

When you combine the endpoints with these actions, you can search or update any available information over an API. You’ll need to check the API documentation to find out how to code these actions, as they’re all different.

While we’re talking about language and syntax, let’s cover the ways you can make a request on a server:

HTTP: hypertext transfer protocol. This is how you got to our site in the first place — by typing a URL in the search bar in your browser. This is a really easy way to access data, but it won’t come back to you in a pretty format if you request a lot of information. We’ll go into this further in just a second.

Text formats: XML, JSON. These are the main languages for accessing data over an API. When you receive your data, you will need to wade through the XML or JSON code to understand what the server gave you.

Start Using an API

Many of the API uses you’ll see in your daily business lives move information from one program to similar form fields in another program. This is especially useful when you’re trying to share information that you would otherwise have to enter repeatedly — e.g. sharing leads between your marketing automation platform and your CRM.

The uses and examples we’ll list here are much more basic and pull much less data than what your standard API is good for. But they’ll give you a good idea of the steps in the API process.

  1. Most APIs require an API key. Once you find an API you want to play with, look in the documentation for access requirements. Most APIs will ask you to complete an identity verification, like signing in with your Google account. You’ll get a unique string of letters and numbers to use when accessing the API, instead of just adding your email and password every time (which isn’t very secure — for more information on authorizations and verifications, read this).
  2. The easiest way to start using an API is by finding an HTTP client online, like REST-Client, Postman, or Paw. These ready-made (and often free) tools help you structure your requests to access existing APIs with the API key you received. You’ll still need to know some of the syntax from the documentation, but there is very little coding knowledge required.
  3. The next best way to pull data from an API is by building a URL from existing API documentation. This YouTube video explains how to pull location data from Google Maps via API, and then use those coordinates to find nearby photos on Instagram.

Overall, an API request doesn’t look that much different from a normal browser URL, but the returned data will be in a form that’s easy for computers to read. Here’s what happened when I requested information from the OpenWeather database in my web browser:

Example URL from documentation — request weather for a particular city:

api.openweathermap.org/data/2.5/weather?q={city name}

Type into your browser:

api.openweathermap.org/data/2.5/weather?q=Nashville,TN&APIID={numberslettersnumbersletters}

OpenWeather API responseConclusions and Further Reading

An API is useful for pulling specific information from another program. If you know how to read the documentation and write the requests, you can get lots of great data back, but it may be overwhelming to parse all of this. That’s where developers come in. They can build programs that display data directly in an app or browser window in an easily consumable format.

This article barely scrapes the iceberg that is API technology. I researched the web quite a bit to learn about APIs. These are the articles and videos that helped me the most:

Want to connect your programs, but don’t have the time to build a client? There are plenty of companies out there that will connect existing APIs or build custom connections for you. These can range from simple data-triggered apps like Zapier to full-scale business intelligence integrations that pull huge amounts of data from multiple sources for analysis. Knowing how an API works is the first step to building great integrations.