What Is an API — The Agreed Rules Programs Use to Exchange Data, and JSON

This article covers APIs.

An API is the agreed rules programs use to exchange data.

It goes through the three parts of a call and JSON, the text format that comes back.

• What "calling an API" actually sends, and where
• The three parts of a call — URL, method, response
• How to read the keys and values of the JSON that comes back
• The status code that shows success or failure, and what to do next for each number

"Calling an API" means sending a request to a set URL and receiving a response

The weather data is not held by your own program but by an external service's server.

An API called with HTTP requests and responses is a Web API, and each URL it accepts is an endpoint.

An external service can be the provider, and so can the my-app server.

And one screen does not necessarily call just one endpoint.

Three request-and-response round trips happen before the page appears.

The only thing the browser connects to directly is the my-app server.

The same server is the provider from the browser's side and the caller from the weather API's side.

Calling an API means sending and receiving

Calling an API means sending a request to a set URL and receiving the response that comes back.

Each of those URLs is an endpoint; the caller can be the browser or your own server, and the provider is not necessarily an external service.

The three parts of a call — URL, method, response

Setup instructions and documentation give you only three things.

Where to send it (URL), what you want to do (method), and what comes back (response).

The first of these, the URL, splits into two roles at the ?.

What follows the ? is a parameter — a condition for the data you want, added to the end of the URL as name=value — also called a query parameter.

The second part is the method — a set word such as GET or POST that says what you want the request to do.

You write it at the start of the line, and it changes the behavior even when you send to the same URL.

GET does not change the other side's data, but POST changes it the moment it is sent.

Setup instructions write this as a method followed by a URL.

Lines starting with # are explanation, and the line below each one is how to call it.

# Get the weather. The method comes first, the URL after (parameters at the end)
GET https://api.example.com/weather?city=tokyo

# Register one booking. Same URL, different method, different behavior
POST https://example.com/reservations

The document that collects how to call it and the shape of the response that comes back is the API documentation.

When instructions say "see the API documentation", that is where you look up the three parts.

You decide only two things before sending

Before sending, you decide only two things: where to send it and what you want to do.

Where to send it is the URL, with the part before the ? being the endpoint; what you want to do is the method. The third part, the response, is the one you do not decide — you read whatever comes back.

JSON is a text format that writes data as key-and-value pairs

The "JSON that came back" in the instructions is the body of the response.

JSON — a format made of text only, which writes data as key-and-value pairs — is the format most commonly used for Web API bodies.

The JSON the weather API returns looks like this.

{
  "city": "Tokyo",
  "temp": 23.5,
  "rain": false,
  "forecast": [
    { "day": "mon", "high": 25 },
    { "day": "tue", "high": 22 }
  ]
}

These are key and value pairs — the key is the name given to a value, and the value is the content that name points to.

In "temp": 23.5, temp is the key and 23.5 is the value; a key and value are joined with :, and pairs are separated with ,.

Pairs are listed inside { }, and a value can itself be a [ ] or a { }.

The fourth value is an array — several values listed in order inside [ ] — and each item is again wrapped in { }.

{ } and [ ] can be nested to any depth.

To take one item out of an array you point at it by number, such as [0], and the numbering starts at 0, not 1.

Values that are not [ ] or { } are written in three ways, and you tell them apart by whether " " is used.

As received, the body is one long string, so naming a key does not get you the value.

In introductory books you first convert it into a form whose keys can be read, with a single line such as JSON.parse, and then point at a value by key name, such as data.city.

Only the bottom row has the key spelled wrong on purpose, by one character.

A misspelled key does not raise an error, so when you get undefined, first compare the spelling against the JSON.

The name contains JavaScript, but it is used for API responses because any language can read and write it.

JSON is just a list of name-and-content pairs

JSON is nothing more than a sequence of text listing pairs of a name and its content.

The name is the key and the content is the value; as received it is one long string, so you convert it into a form readable by key before taking values out.

A response is not always a success — the status code decides what you do

The weather API runs outside your own program, so a call can fail.

That is why a response does not arrive as a body alone.

Look at what comes back as separate parts.

The three digits at the front are the status code — a number that shows whether it succeeded or failed and of what kind.

Look at the number first, and read keys from the body only on success.

You do not memorize all three digits; the first digit decides what you do next.

Even with the same weather API, the number that comes back changes with what you sent and the state of the provider.

Besides 404, a 500 comes back when a fault occurs on the provider's side.

404 is not only the number for "no such page": with an API it also comes back when no data matches the parameter conditions.

When you call it as instructed and get a 404, compare the spelling and the parameters against the API documentation.

Among the numbers starting with 4, 401 is the one for when there is nothing showing who the caller is, or what is there is not correct.

The API key is what you attach to the request to show that.

Read the number before the body

When a response comes back, look at the number before reading the body.

If it starts with 2 the body holds the key you want; if it starts with 4, fix the URL and conditions you sent; if it starts with 5, wait a little and call again.