APIs allow us to leverage a 3rd party’s computing power and features, programmatically. In simple terms, we send some input data to a certain endpoint and receive a processed result back. An API can provide us with a variety of possibilities, from simple text processing to building out entire websites. This is the standard way of creating a communication channel between us and a 3rd party. In this article, we’re going to learn what an API is and how to use them.
What is an API?
An API, short for Application Programming Interface, is a way of creating a communication channel between 2 pieces of software. One part makes available some functionality for the other to be able to use it. The API itself is the collection of features that are available.
APIs are used by a lot of companies to make their data available to other developers, including companies like Facebook, Google, and Twitter. For example, all 3 of those companies makes available user data to developers, with the user’s permission. You’ve probably logged into a site, at least once, via Facebook, Google+ or Twitter. That function is using an API to grab your profile information after you authorize it to do so.
What is REST
REST stands for Representational State Transfer and is an architectural style that defines a set of constraints to be used for creating web services. This mainly refers to how HTTP endpoints are defined. An endpoint is a URL, you can think of it as an entry point too. APIs need specific endpoints to do specific actions and, as with anything else, we needed a naming convention. This is where REST comes in. REST is the naming standard of the endpoints.
For example, let’s say we have access to an API that allows us to list all of our emails in our account. The endpoint would be called:
/emails/list
And because we retrieve something, we would use the GET HTTP method. So the request would be defined as:
GET /emails/list
It’s important to understand what that means because all of the API documentation manuals follow this convention. They specify the method, and then the endpoint.
But we’re missing a piece. We need to know the base URL to create the request. This is usually specified at the beginning of the documentation, and the base URL never changes. Here are some popular naming conventions for API base URLs. However, keep in mind that this is not standardized, so yours might differ.
- https://api.company.com/1.0
- http://company.com/api/
- https://company.com/api/2.0
So, assuming that the first in the list is the base URL for our example from before, to list our emails, we’d have to create an HTTP request of type GET to https://api.company.com/1.0/emails/list.
The 1.0 and 2.0 in the URLs represent the API version. This is often used by large APIs to maintain backward compatibility when they upgrade the API.
A Word About SDKs
An SDK, short for Software Development Kit, is a wrapper over an API. Following our previous example with listing the emails, if that API had an SDK, instead of having to create that request ourselves and check the returned result, we could simply do something like this:
const sdk = require('sdk-name');
let response = sdk.emails.list();
There’s no naming convention here, but often SDK developers will try to name components as close to the API endpoints as possible.
That last line of code would create the GET request to the specific endpoint and return a response. If the JSON is valid JSON, it would automatically be parsed into a valid JS object, so that all you have to do is use the object.
Some APIs come with an SDK, for some APIs you’ll find SDKs developed by other users that aren’t in charge of developing the API itself, and some APIs don’t have SDKs at all. You can also create your own SDK.
General Notes
All APIs have some kind of documentation that goes along with them. That’s why the first step in using an API is finding the documentation. You can find it by searching for the company name and the words developer API; e.g.: facebook developer API. The first Google result will take you to developers.facebook.com, where you’ll find a link to the Docs (documentation).
All API documentation manuals will contain a list of endpoints and their specific parameters. If the API includes an SDK, it will also show you how to use the SDK to perform the request on a specific endpoint. You can always do the request manually, but most of the time SDKs get rid of a lot of code for you, so whenever there’s one available, you should use it.
An endpoint can have a list of supported parameters that go with it. Some are optional, some are required. In some cases, the parameters are also validated against a specific type. This will also be specified in the API docs.
Response Types
Whenever you create a request to an API endpoint, it will return some type of response. Because this is meant to be used in a programming language, the response will always be sent in a parseable data structure. The most common response types are JSON and XML. They’re used because they can easily be parsed, either with the help of a library or using a predefined language function. Some programming languages support parsing functions for JSON and XML.
JSON tends to be more widely used nowadays because it’s easier to read in its stringified form, and because it takes up less space than XML. Response length can become a problem when you’re doing thousands of requests in a certain amount of time. They can add up real quick and they end up wasting both processing power when parsed, and bandwidth, when transferred.
For the sake of keeping things simple, we’re going to only cover JSON in this article, but using XML is very similar, you just change the encoding and decoding functions.
API Identification & Limitation
Some API providers need a way to limit the usage of their API in order to be able to function. This is implemented via the concept of applications. An application is an entity able to access an API. This isn’t only used for limitation, it can be used to provide statistics, count the number of requests, and so on. It’s simply an identification system for each API endpoint request. Once the API provider is able to ID your every request, since every request will include the app’s ID or public key, they can limit you to a number of request per second or per day. These limitations are also featured in the official docs.
The way it works is this: You create the application and give it a name that describes where you’re going to use it. In return, you’re going to receive an app secret key and a public key. The public key is often referred to as simply the API key. The basic concept is to have an app secret key and a public key, but services that provide APIs choose to call them differently, for example, some call the public key “app ID”, like Facebook. So don’t be surprised if you’re going to see them called: Client / Server keys, API / Secret keys, App ID / Secret keys or something similar.
Also, sometimes the secret key is optional. But the main key, the public key, is always present if the API provider has asked you to create an app to use their API.
Note that some APIs don’t require you to create an app, that’s an option too. An example of this is TV Maze’s API.
API Authentication
Because API endpoints are public, when we handle private data, we need some type of authentication to protect our data from being accessed by others.
Let’s discuss the 3 most used methods of API authentication.
HTTP Basic Authentication
This is a very old and very simple form of authentication, as the name implies. You simply include a request header called Authorization with the value in the form of <Basic Password>. E.g.:
Authorization: Basic ZnJlZDpmcmVk
The hash would be a unique hash assigned to your own app.
API Keys
We’ve talked about this before. They work in the context of an app and they ID you through them. You create an app through the site that offers the API and you get a public key and a secret key (optional). Based on the terms of service, you send either the public key alone, or the secret, or a combination of the two with every request.
OAuth
This is a combination of authentication and authorization. This also relies on API keys and it’s how Facebook’s apps work. You create an authorization URL based on the API keys, redirect your users to that URL, they log into their Facebook account and authorize your app. Facebook then redirects back to your server with a hash, called an authorization token. Then you use that token with every endpoint request. This method is by far the most secure, but it’s also pretty complicated to understand. If you want to read more, I recommend this article on How OAuth Works.