3. How to Use an API:
Just the Basic
APIs are less like USB ports or fire hoses than they are as 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 to do anything with this data.
What is an API?
API stands for an application programming interface. The most important part of this name is interface
, because an API mainly 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 making URLs or using HTTP clients (special programs that develop 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.
Why Should You Use an API?
Computers make a lot of things more comfortable, 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.
The 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 external user can then query (or search) the info 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 the 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
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 would not 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 a usable form. You can code your application 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
Many companies use 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 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. At the same time, 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 limit 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 request 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. This 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 syntaxes 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 the existing API documentation. This YouTube video explains how to remove 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}
Conclusions and Further Reading
An API is useful for pulling specific information from another program. If you know how to read the documentation and write 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 you the most: