Table of Contents
What is an API?
API stands for Application Programming Interface. In this context, an application can be any software you use, either locally on your computer such as Microsoft Word or hosted online like Gmail. The second half, "programming interface" simply refers to something that you can interact with via a programming language such as Python or JavaScript.
APIs allow developers to write code to interact with the data stored inside of an application without having to interact with the application’s user interface – there is no need to open the application. A request is sent to the API, it processes it and gives back a result or performs an action inside the application. This could be fetching or sending an email from Gmail or changing or deleting details about a task in Asana, such as marking it as complete, assigning it to a new person, or appending a document.
What you can do with an API depends on what the application developers have decided to provide access to. Some APIs are very limited, while others allow you to access everything inside of the application. Some examples of actions you can perform in Gmail through their API include, create a draft email, send a draft email, add a label to an email, mark an email as important, move an email to a new folder, and many more.
Once coded, simple tasks could be automated, such as sending an email with the press of a button. More complex automations are also possible: a user might fill in a form on a website, and through APIs the meeting is scheduled, the invite is sent, a room has been created in Zoom, a personalized confirmation email sent, and a task appears on the right employees’ task/time management software.
Creating an API is a lot of work and unfortunately, not all applications have them. This will severely limit your ability to access data stored inside of the app and to integrate with other apps. When choosing new software to implement, it's important to make sure it has a robust API.
Making a Request
Web-based APIs are accessed through internet requests. A request is what is sent to a server each time you type a URL into a browser and hit the enter button. Requests first locate the server behind the domain name and then help the application know what webpages to show you. In the case of APIs, these requests are made to endpoints that specify what kind of data or action you want to access or perform. We will cover endpoints in the following section.
Before continuing it's important to know that a single request can contain a lot of information. When making requests online using a browser, many complicated components are handled in the background. This allows the user to focus on just the URL and, well, pressing buttons on the page. Requests contain a method type to inform the server what action you’re trying to achieve. Requests also contain Headers to tell the server information about who you are. This prevents Gmail from showing you another user's emails. Requests can also contain a Body which carries additional information. We'll return to request Operations and Bodies in the section on Basic Operations and to Headers in the section on Authentication.
Endpoints
Endpoints are API URLs that a program will go to, much like a human goes to a URL through their browser. Instead of the server showing you a website, the server knows that you’re accessing the API so it will perform some action instead. An example Gmail endpoint might look something like:
This is a completely made-up example but it's common to see the text “API” inside of the API endpoint and it's also quite common to see the letter “v” with a number to indicate the API's version. As technology progresses, applications that have been around for a long time are likely to have multiple versions of their API so it’s important to make sure you’re accessing the correct version. Finally, the end of the URL tells us that we want to access emails. Perhaps if we wanted to access Gmail contacts, we would instead go to the following endpoint:
Great, now we know how to access an API endpoint, but how does Gmail know whether we want to create a new email, see all emails, change the label of an email (read to unread), or just view one specific email? Let’s take a look at basic request operations.
Basic Operations
Although there are some uncommon operations that an API can support, APIs generally support four basic operations, GET, PUT, POST, DELETE. These four operations are extremely common and allow a single endpoint to perform many functions. The type of operation you wish to perform is passed along to the API when you send your request to an endpoint. Using our previous example endpoint www.gmail.com/api/v2/emails, let's explore how each of these four operations allow us to do many things with just a single endpoint.
GET
The GET operation is used to retrieve data inside an application. For example, we could expect that making a GET request to the endpoint www.gmail.com/api/v2/emails would return a list of all emails in that Gmail account.
What if we don’t want every single email and instead just a single email? Well, we would use GET for this too. Inside Gmail's database, every single email is assigned a unique identifier. This identifier is usually a number or a hash that a computer can process extremely quickly. This helps the application keep track of all of the "objects" within it. Objects represent items in the application and in the case of Gmail, the "objects" we’re interested in are emails. If we can find the unique ID of the specific email that we want to access, let's say 100012 for this example, we could expect the endpoint www.gmail.com/api/v2/emails/100012 to return data about the single email assigned with this ID.
PUT
The PUT operation is used to update the information of an "object" in an application. In our Gmail example, these "objects" are emails. Perhaps we would like to change an email’s status from read to unread. We know from the previous section about GET operations, each email has its own unique ID. Using this unique ID and the PUT operation on our endpoint www.gmail.com/api/v2/emails/100012, we can pass some data to this endpoint, typically through the request’s body, which tells the API to update an attribute of this email. To change the read status of an email, the developer may include something like the following in the body of the request: {"read": false}
This format is known as JSON and is just a format for transferring data in a way that’s easy for both humans and computers to read. By sending a request with the operation PUT and the previous body to the endpoint www.gmail.com/api/v2/emails/100012, Gmail’s API will know to update the read status of the email with the unique ID of 100012.
POST
The POST operation is used to create new "objects" inside of an application. Continuing with our Gmail example, the "objects" that we’re interacting with are emails. To create a new email via an API, your code would likely send a “POST” request to the endpoint www.gmail.com/api/v2/emails/100012 with a body containing all of the information that you want the email to contain. Our example API expects the body to be in JSON format so that is what we will use. Although JSON is currently the most common format for most API requests, it is possible for an API to require a different format.
```JSON
{
"subject": "This is the new email's subject",
"body": "This is the body content of the new email",
"to": "sendtouser@user.com",
"cc": "ccthisusertoo@user.com"
}
```
Now a new email will be created using our Gmail account with the attributes of the JSON determining the content of the email. Often, there are required fields to create a new object through an API and any non-required fields will be set to some default value.
DELETE
After reviewing the previous operations, the DELETE operation is very straightforward. We would expect that sending a DELETE request to the endpoint www.gmail.com/api/v2/emails/100012 would delete the email with the unique ID 100012.
Authentication
Before using an API, you must figure out how to prove to the API that you have permission to perform actions on behalf of the account that you are using. Essentially, that you are who you claim to be. Continuing with our Gmail example, Google wants to make sure that you are the owner of the Gmail account before allowing you to create, read, update, or delete emails.
There are many types of authentication methods that an API can use and it can get slightly technical so we will not cover this topic in too much depth in this introductory article. Most applications will have an API key that you can generate. This API key must either be included in the Header or sometimes directly inside of the URL path. For example www.gmail.com/api/v2/emails/?api-key=this-is-your-api-key. For keys required in the Header, you can just think of the Header as a container for metadata about the user or machine sending the request. Sometimes an API will want you to use your normal username and password instead of an API key to access the API.
API Errors
The exact errors you will see working with an API depend on the API. For example, using Gmail, if you entered an invalid email address to send the email to, perhaps the API would respond to the request with an error saying "Invalid 'to' email address". There are also many errors you could see in regards to Authentication, perhaps your API key is incorrect or out of date, or the API expects it to be passed in a different location or format.
With that said, there are standard HTTP response status codes that most APIs follow. These codes alone are enough to determine whether the request was successful or not. Here are some of the most common HTTP status codes:
At a very high level, HTTP response status codes in the 200s denote a successful API transaction. All other status codes signify some sort of error.
Rate Limits
To avoid one user consuming too many server resources, APIs will typically enforce a limit to the number of requests that a single user can make within a defined time window. This is often expressed in minutes, although some may use seconds. For example, an API may have a maximum of 120 requests per minute, or perhaps, 10 requests per second.
API Documentation
Each API should provide documentation that you can read to better understand the specific conventions and expectations of that API. Although there are general best practices, it’s ultimately up to the developers at an organization to decide how they want to handle everything. . API documentation should provide explanations and examples for how to successfully handle:
Key Takeaways
To recap, APIs are powerful interfaces that allow code to communicate with other systems. They allow developers to open their applications to other systems for integration, such as automatically importing bank transaction information into some accounting software to streamline bookkeeping. Anytime you perform an action inside of one platform that causes more actions in another platform, you have powerful APIs to thank.
APIs open the door to time-saving automation and allow code to take over the painful job of transferring data between systems or manually creating many objects. The next time you find yourself repeating a tedious manual task inside of a modern web application, consider investing in a little custom code to take care of it for you.
Integrating APIs and getting systems talking to each other is our bread and butter so feel free to get in touch with any questions. If you would like our experts to get your systems talking and automate your tasks, just fill in the form below.