Skip to content

APIs 101, pt 2: How to talk to an API: requests, responses, and examples

What's an API, again?

In the first post of this series, we discussed what a REST API is: an application interface that enables programs to exchange data cleanly, reliably, and securely.

This second installment discusses API requests and responses: the bread and butter of how APIs ask for and receive information. In other words, it's how your favorite apps know that it's probably going to rain later, or how a certain meme stock is doing today.

Anatomy of an API request

To interact with an API and access data, programs send a request that lets the API know which data to retrieve and what to do with it. There are a few basic components to an API request:

Endpoint/URL

The web address you're calling. Just like a mailing address, it routes the request to the correct location. For example, **https://catfact.ninja/fact.

HTTP method

An HTTP method specifies what you want the API to do with the data. There are four basic methods:

  • GET: Ask for data; for example, getting the latest stock price or weather prediction (or cat fact!). We'll focus on this method in the rest of our example.
  • POST: Provide new data that you want the API to append to its existing data.
  • PUT: Update existing data.
  • DELETE: Delete data.

Request header

The header is like a note attached to the request with extra details; for example, if you need to provide authentication, or need to specify a content type, this information goes in the header.

Request body (optional)

The goods you are delivering. If you are using a POST or PUT method, for example, the body is where you'd include the data that you want to update or add. GET requests may not have a body.

Interpreting the response

Once the server has received your request, it sends back a response which either makes the update/gives you the data you asked for, or explains why it couldn't fulfill your request. Just like the request, a response has several different components:

Status codes

Status codes are numerical codes that explain the status of the request. You're probably familiar with 404 responses (resource not found). There are a wide range of other three-digit numbers that you can get in response to your request, broken down generally into five classes:

    1. Informational responses (100-199), such as 102 Processing.
    1. Successful responses (200-299), such as 200 OK or 201 Created. These are the ones you generally want to see.
    1. Redirection messages (300-399), such as 301 Moved Permanently, which tells you that the URL or endpoint of the server has moved and gives the new endpoint in the response.
    1. The dreaded Client error responses (400-499), such as 403 Forbidden or 404 Not Found, which indicate that the request was somehow faulty. This may be because you're unauthorized to access certain data, or because the request syntax is malformed. Or because you're a teapot.
    1. Server error responses (500-599), such as 500 Internal Service Error, which indicate that something has gone wrong on the server/API side. This might be because of a storage issue, unhandled exceptions, or some other server issue.

Response header

Just like the request header, the response header contains metadata about the response, such as the content type.

Response body (optional)

The body contains the actual data returned by the API (assuming you've used, say, a GET method that requests data). This is usually in JSON or XML format.

Demo

Now that we know what an API request and response looks like, it's time to get our paws on some cat facts.

Copy/paste this URL into your web browser: https://catfact.ninja/fact

This will return a JSON object with two key/value pairs:

  • "fact": A fact about cats. A cat fact, in fact.
  • "length": The length of the cat fact as measured by the number of characters.

Here's an example:

{
  "fact": "Cats make about 100 different sounds. Dogs make only about 10.",
  "length": 62
}

This JSON, then, is the response body we received from the Cat Fact API. If we wished, we could use it to power something like a "daily cat fact" tracker.

What about the rest of the response? You can look at the response headers in the "Headers" tab. Depending on your machine and browser, this may look a bit different, but you can see more details about both the request and response headers, including when the request was sent, the content type, and more. You can also look in your browser's developer console to see your browser's log of the request and response, including the status code and HTTP method (in my case, a 200 (OK) status code from a GET request).

Of course, a response body can be much more complex and contain lots more information, but good old Cat Facts gives us a simple foundation for understanding how an API receives and supplies information.

In the next post, we’ll crack open the request headers and talk about API keys, tokens, and why some APIs need to know who’s asking before they spill the (itty bitty toe) beans. Stay tuned!