APIer/00 · Prologue: what an API is
CHAPTER 00 · Client, server, JSON

What is an API

You can write HTML and CSS, and you have used some JavaScript. But where does the data on a page come from? This chapter answers that from the beginning.

§01

Start with a restaurant

This is the most useful comparison in the whole course. The other eleven chapters keep coming back to it.

You sit down in a restaurant

You want a plate of noodles. You do not walk into the kitchen and cook it yourself. You sit down, open the menu, tell the waiter what you want, and the waiter passes your order to the kitchen. A few minutes later the food arrives.

Software works the same way. Your web page needs data. It cannot go into another company's database and take it. Instead it follows the format written in the API documentation (the menu), hands the request to the API (the waiter), and the API gets the data from the server and database (the kitchen) and brings it back.

API stands for Application Programming Interface. The full name sounds heavy, but the idea is one sentence: an agreed set of rules for how one program asks another program for something, and how the answer comes back.

The menu
API documentation

It lists what you can order, how to order it, and what comes back. Reading the documentation is reading the menu.

Ordering
The request

What you say, in the format the menu defines. If the format is wrong, the waiter cannot understand you and no food arrives.

Serving
The response

What comes back. It may be the data you asked for, or a message saying the dish is sold out. Both of those are responses.

§02

Client, server, and the full trip of one call

Who asks, who answers, where the data lives, and whose hands it passes through. The player below shows it one step at a time.

Two words to remember. The side that starts the request is the client. The side that holds the data and answers is the server. Your browser and your phone apps are clients. A server is a computer that stays on, running a program whose only job is to listen for requests, do the work, and reply.

One API call, played back step by step
🖥️Browser
🗄️Server
💾Database
You click "View profile" on the page. Your JavaScript now has to get the data. That data is not on your computer. It lives on a server somewhere else.
1 / 7

Why does a web page never connect to the database directly?

Because every line of code in the browser is visible to the user. Press F12 and you can read it. A database password written into front-end code is a public password.

There is a second reason. Someone has to decide which user is allowed to see which data. That decision has to happen on a machine the user does not control, and that machine is the API server.

§03

You have already used APIs dozens of times today

An API is not an obscure technical term. It is closer to plumbing: it is everywhere and you rarely see it.

☀️ Checking the weather

A weather app does not measure the atmosphere itself. It calls a weather service API, receives JSON such as city, 26°C, cloudy, and draws an interface from it.

Paying for coffee

The card reader calls the payment provider's API: charge this customer 4.50. The beep you hear is an API call that came back successfully.

"Sign in with Google"

A site you have never used does not know who you are, so it asks Google to confirm your identity. Your Google password never leaves Google. That mechanism is OAuth 2.0, covered in chapter 06.

Asking an AI a question

Your question is packed into a request and sent to the model provider's API. The answer is the response body. Adding AI to a product mostly means calling that API.

A quick test

Does this feature need data or a service that belongs to someone else? If yes, there is an API behind it. If the device can do the whole job on its own, for example a calculator adding two numbers, there is no API call.

§04

What the data looks like: JSON

More than nine out of ten API responses use this format. Click each line to see what it is.

response.json · click any line
"id": 42,

A key must be a string in double quotes. JavaScript allows unquoted keys, JSON does not. The value 42 is a number, and numbers take no quotes. The comma at the end means another pair follows.

Why JSON?

Early APIs mostly used XML, where every value sits inside a pair of tags. XML is precise but verbose. JSON is smaller, easier to read, and converts to a JavaScript object with almost no work, so it became the common choice on the web. Nearly every public API you meet today returns JSON. Keep one thing in mind for chapter 03: REST does not require JSON. This is a convention, not a rule.

§05

Do not take my word for it. Send a request now

The demo below is not an animation. Your browser really sends a request to a public server.

Send a real request now
Click a button. Your browser really does send a request to a public server on the internet, and the response is printed below exactly as it arrives.
§06

Two ways to order: the main line of this course

The same kitchen can accept orders under two very different sets of rules. Those two are REST and GraphQL.

REST
Fixed sets

The menu lists fixed dishes. Each URL identifies one resource, and the server decides which fields come back. The rules are simple and the style is used almost everywhere, so REST is the common language of today's APIs.

GraphQL
Choose your own

One order form where you tick what you want: which fields, and how many levels of related data, all stated in a single request. The server returns exactly that. Facebook created it to solve problems in its mobile app.

These two styles cover most APIs in use today, and they are the main line of this course. The full map is below. Start at the top left and work down. The small dots in the sidebar record your progress.

§07

Labs

Reading is not the same as knowing. Three tasks, about ten minutes, and you will have made your first API call today.

§08

Chapter quiz

Seven questions. Get them all right to light the dot in the sidebar. Every wrong option has its own explanation.

QUESTION 01 / 7

What does the word "interface" in API really mean here?

QUESTION 02 / 7

You open a weather app on your phone and it shows 26°C. In this situation, which side is the client and which is the server?

QUESTION 03 / 7

Which statement about JSON is correct?

QUESTION 04 / 7

Why does your web page go through an API server instead of connecting to the database directly? The main reason is:

QUESTION 05 / 7

Which of these everyday actions almost certainly involve an API call? (Select all that apply.)

QUESTION 06 / 7

The built-in function most often used in browser JavaScript to send a network request is called ____ (lowercase, five letters).

QUESTION 07 / 7

In what form does the JSON from the server travel across the network, and what must you do first before you can read data.name in JavaScript?

What to take away from this chapter
  • An API is an agreed set of rules for how one program asks another for something and how the answer comes back. The menu (documentation), the order (request), and the food (response) are the three things this course is about.
  • The side that sends the request is the client. The side that answers is the server. The roles come from who asks and who answers, not from the type of device.
  • Front-end code never connects to the database directly. Nothing in the browser is secret, so the API server is the checkpoint that keeps credentials and decides who may read what.
  • Only text travels over the network. JSON is the common format for that text, and response.json() turns it back into an object you can use.
  • REST serves fixed sets, GraphQL lets the client choose. They are two ways of ordering, and neither replaces the other. The final chapter shows you how to choose.