NEW

Prismic offers an ideal solution to feature your e-commerce products in your promotional landing pages or inspirational content. View more

How Do APIs Work?

Written by Sam Littlefair in
concept
on June 01, 2022

If you’re reading this page (and you are), you’ve already made at least one API request today. But making an API request is easier than knowing how to make an API request — or even what an API actually is.

In basic terms, an API is a connection between two computers or two computer programs. Here are some examples that use APIs:

  • Retrieving a web page in a web browser
  • Using a keyboard to enter text on a computer
  • Saving a word document to your computer’s file system

API is an acronym for "Application Programming Interface." On the web, "API" often refers specifically to networks of computers in warehouses that store and manage information for websites, allowing you to retrieve web pages.

How do APIs work?

A message that you send to a web API is called a “request.” The computer that sends the request is called the “client.” The computer that fulfills the request is called the “server.”

Often, the client sends a request for data (like, "What's the weather?"), and the server responds with an answer ("Currently warm and sunny"). But the client might also ask the server to do something (like, "Add milk to my grocery list"), and the server could respond with a status ("Done").

Here's an example

Imagine you're browsing your favorite news website. You type "politics" into the search bar and hit "enter." The web page says to the API, "Hey! Retrieve all the results with the word 'politics.'" The server returns those API results, and the web page updates with the search results.

Diagram that shows a computer (the client) making an API request when you search for the term "politics" on a news website. The API request goes to another computer (the server) that responds to the request; in this drawing the server says, "Here you go!"

On the internet, there are many ways to transfer data. For example, emails move via SMTP and files can move via FTP. The part of the internet that you view with your browser is the World Wide Web, and it uses a protocol called HTTP to transfer information. Information is sent and received in HTTP via API requests. (In fact, when you type a URL into your browser's address bar and hit "enter," that's an HTTP API request — which is how you’ve probably already made many API requests today.)

HTTP is the foundation of the web because it's the standard method for requesting information. HTTP stands for Hypertext Transfer Protocol, because it was originally meant solely for transferring web pages, which are written in hypertext (HTML, or Hypertext Markup Language). Today, you can use HTTP for sending and receiving many different file types.

Every HTTP request includes a method to declare what kind of request it is (like when you call a friend and start the conversation by saying either "I have a question," "I have some news," "I learned something new," or “forget what I told you”). The most popular methods are GET (to request a resource), POST (to create a resource), PATCH (to update a resource), and DELETE (to delete a resource).

A drawing that represents the four types of API requests: GET, POST, PATCH, and DELETE. If you called a friend on the phone, a GET request would be like saying, "Can you tell me something?" A POST request would be like saying "I have some news to share." A PATCH request would be like saying, "I learned something new." And a DELETE request would be like saying, "Foret what I told you!"

Every HTTP request also includes a URL, which is the address for the resource. The URL includes the domain (like "google.com"), but it can also include a lot more information. For example, this is a URL for the Pokemon API. The URL includes the domain, the API endpoint, and parameters specifying that the client would like four Pokemon starting from the twentieth.

 
https://pokeapi.co/api/v2/pokemon?limit=4&offset=20

The parameters are the information that comes after the ?. A URL parameter generally includes information for the API to use when processing the request.

Here’s how that breaks down:

  • https://: This specifies the protocol, which is HTTP.
  • pokeapi.co: This is the API endpoint (we’ll cover that later).
  • ?: The question mark specifies that what follows will be optional parameters.
  • limit=4: This is a parameter specifying that the API should return only 4 pokemon.
  • &: The ampersand marks the next parameter.
  • offset=20: This is a parameter asking the API to skip the first 20 pokemon.

If an HTTP request is successfully delivered, it will receive a response from the server. If not, the request will eventually time out.

What’s the “S” in “HTTPS?

In HTTPS, the “S” stands for “secure,” because HTTPS uses a connection protocol that is more secure than regular HTTP because it is encrypted by a verified source.

What is an API endpoint?

An endpoint is one part of a web API. Specifically, it is a URL that points to a server where a client can send HTTP requests. When an endpoint receives an API request, it executes code that processes the request and takes action, depending on the HTTP method, and either creates, reads, updates, or deletes a resource on the server.

The code that the API executes is provided by a developer, and it could do anything — so long as it adheres to the general principles of HTTP. The request could even ask the server to perform a physical action, like turn on your lights or open your garage door (provided you have the right hardware installed and connected).

What is a REST API?

REST is a specific set of guidelines for creators of HTTP APIs. REST guidelines standardize the structure of API requests and the responses.

Many developers prefer REST because it is very explicit about what API requests should do and how the API should behave. As a result, REST APIs are generally seen as being easy to work with.

That’s why Prismic chose to build most of the APIs for our product (a headless website builder that allows you to add a CMS to your app through an API) as REST APIs. They make it easy for developers to utilize the data created by their content teams in their code.

What is JSON?

REST APIs can return information in many formats, but the most common is JSON, which is the format that the Prismic API uses.

JSON (which stands for "JavaScript Object Notation") is derived from the JavaScript programming language, but today it is language-agnostic and one of the most popular formats for sending and receiving data. JSON is notable for being relatively easy to read. Here's an example of valid JSON data:

 
{
  "name": "Stuart",
  "age": 9,
  "student": true,
  "pets": [
    "Sophie the Dog",
    "Arnold the Lizard",
    "Chirpy the Bird"
  ]
}

As you can see, you don't need to be a computer (or a computer nerd) to read or write JSON.

Developers can write programs to use this data:

 
Welcome! {name} is {age} years old.

Which would output text like this:

 
Welcome! Stuart is 9 years old.

How can you use an API?

As we said before, sending an API request is as easy as typing a URL into your address bar. But APIs can do a lot more than retrieve web pages.

If you already know the basics of the JavaScript coding language, then you could play with the Prismic API. To get started, see the Prismic documentation. Prismic’s main API is a REST API for delivering content created in the Prismic web app. So, you can create content in Prismic and then fetch that content in your code.

You can also stay tuned for the next installment in this series, where we’ll share a few cool APIs that you can play with to learn and master API requests.

Sam Littlefair

Sam Littlefair

Sam is a Canadian in France preoccupied with journalism, web publishing, JavaScript, meditation, and travel. He works on documentation at Prismic.

More posts