What is an API?

An application programming interface (API) facilitates communication between technology products and systems. It is sometimes said that APIs “help machines talk to other machines” because by communicating through a structured set of rules, APIs let you programmatically interact with systems instead of using a web interface.

Along with accomplishing the tasks usually completed through a web interface, APIs enable you to integrate with existing applications and automate processes. There are thousands of APIs available on the web, many of which are free to use. You can reference an API directory like the Postman API Network or go to the service or product you want to integrate with to see if they have an API.

While there are multiple types of API architectures, this guide will focus on one of the most common: Representational state transfer (REST). Web services that conform to the REST API style are known as RESTful APIs. RESTful APIs use HTTP, and in this guide you'll see how a call to a RESTful API looks a lot like a webpage URL!

Before you begin

We recommend reading the What is caching? essentials guide to understand what we mean when we refer to requests, responses, clients, and servers in this guide.

APIs in action

You have probably encountered APIs in action without even realizing it! Imagine you’re on the website for your favorite local taco restaurant ordering lunch. At checkout, you need to enter your delivery address. You start typing your address in a search bar and it auto-completes the city, state, and zip code. Next, you need to enter payment information. You notice the payment fields are processed by a trusted mobile payment service. Finally, after you place your order, you can sign up for a loyalty program and earn rewards based on your order. The website lets you sign up using your preferred social media platform.

The address auto-completion, payment processing, and social media sign up are all examples of integrating with APIs. Instead of having to create each of these components, the website uses the Google Maps API to easily collect delivery addresses, the Square API to integrate with Square’s payment processing system, and the Facebook API to quickly make rewards accounts.

How do REST APIs work?

REST APIs use HTTP requests and responses to exchange information across the internet. This is beneficial because a web client making a request and the API server providing the response speak a common language. The message request and response themselves use a common HTTP web protocol.

There are many common use cases for REST APIs, typically along the lines of standard create, retrieve, update, and delete (CRUD) database functions. For example, REST APIs can perform create actions, like using the Facebook API to create a new rewards account. They can also retrieve data, like using the Google Maps API to retrieve addresses. For the remainder of this guide, we’ll focus on data retrieval for simplicity’s sake.

Anatomy of an API request

Let’s get into the anatomy of an API request. An API request has five parts:

• The base URL, which is the prefix for the endpoint.
• The endpoint, which tells the request where to go.
• The method, which determines the type of request taking place.
• The headers, which provide information that helps the client and server talk to each other.
• The body which contains the information you want sent to the server.

Let’s dig a little deeper.

Here is an example of an endpoint for the Google Maps Places API:

https://maps.googleapis.com/maps/api/place/autocomplete/

This endpoint has two components. The first is the base URL. This is the domain where the API is served. In this example, https://maps.googleapis.com is the base URL. The path of the endpoint determines the resource you’re requesting. In this example, we’re requesting a specific resource of the Google Maps Places API called Autocomplete. This makes /maps/api/place/autocomplete the path.

You might’ve noticed this looks a lot like a URL. That’s because it is! Remember, this request is happening over HTTP. You could put this in your browser and get a very basic HTML page with the response formatted in different ways depending on the API, with JSON being one of the most common response formats.

However, to actually do something with the API, you need a few other components. The first is a method. Methods are predefined keywords that must be included in every request. The most common methods are related to the CRUD operations: POST (create), GET (read), PUT (update), and DELETE. The method tells the API what you want done, and each endpoint expects a certain method.

Another component used to call an API is a request header. A request header is an HTTP header. It provides additional information about the context of the request. For example, a request header might indicate the preferred language to receive the response. Most APIs also require authentication headers, which provide authentication information to the client like a personal key that shows the person using the API is legitimate.

Depending on the method, you may need to define additional data in the body of the request. For example, if you are creating something using a POST method, there might be data fields used on creation that you need to input.

For example, let’s consider the user registering for an awards account. The user fills out certain fields on your website to create their account. In the backend, an API is invoked, and the details the user entered are used in the body of the request:

1{
2"first_name": "Kris",
3"last_name": "Owner",
4"email": "krisowner@email.com",
5}

Calling an API

Now that you know what makes up an API request, how do you actually call one? To instantly test an API and see the response, you might send the request via curl or an application such as Postman.

For example, let's say you wanted to retrieve the details for a specific user account. The response may look something like the following:

1HTTP/1.1 200 OK
2Content-Type: application/json
3
4{
5  "comment": "",
6  "created_at": "2020-04-27T19:40:49+00:00",
7  "deleted_at": null,
8  "customer_id": "x4xCwxxJxGCx123Rx5xTx",
9  "first_name": "Kris",
10  "last_name": "Owner",
11  "email": "krisowner@email.com",
12}

The response returned depends on the API and the request you made. Let's break this down. The first line contains the status, which in this case is 200 for success. In the next line, the Content-Type header indicates the format of the information you requested, which in this case is JSON. Finally, the body of the response contains the details about the user.

Here, we have demonstrated calling an API for a simple retrieval. You could probably get the same information by logging in via the web interface of your application. The more likely use case for calling an API is incorporating the request into your application and doing something with the data you receive in the response.

How to work with the Fastly API

The Fastly API is a RESTful API that provides access to all the features available through the Fastly web interface.

By using the API, you can work with the objects related to Fastly services and accounts in the way you choose, whether that’s integrating with your existing workflows or automating oft-repeated or cumbersome processes. For example, you might use Fastly’s real-time analytics API to integrate Fastly analytics into your custom analytics dashboard. Or, you may choose to set up an automated purging process. The possibilities are limited only by your imagination (and your programming skills!).

The Fastly API provides a variety of endpoints that we document in our API reference documentation. The endpoint documentation for each API call shows the method, path, authentication type, resource, and parameters that must be combined with the base URL to form a request. Fastly also provides several client libraries to choose from to make and process your API requests and responses. A client library makes it possible for you to use a specific programming language to make and process API requests and responses, thereby reducing the amount of code you need to write.

Best of all, the Fastly API is free to use! In order to start using our API, you will need a Fastly account (you can sign up and test up to $50 worth of traffic for free) and an API token. You can create an API token in the Fastly web interface. It’s used to authenticate your identity so we know the API request is coming from a legitimate source. Check out our API reference for more information on getting started.

What’s next

The API reference guide on Developer Hub has everything you need to get started using the Fastly API. For a complete index of all API endpoints provided by Fastly, refer to this page.

Have you signed up for a Fastly account? There's no obligation and you can test up to $50 of traffic for free.