On this page

Notes · Block 1 · Week 2 · The second interface: APIs

API as the Second Interface

How your UI talks to a machine it has never met, worked out from the machine's own replies. On a customer site, most of the wiring an FDE does is exactly this conversation.

Self-pacedReading time ≈ 12 min

The one thing to keep

Every request between two machines carries four things: an address, an action, a key, and a package in a format both sides agree on. Every reply carries two: a code and a package.

How These Notes Are Organised

Part 1 · Sections 1 to 4

What this lesson covers

Round Three as a worked example, the six parts, and the CRUD quiz.

Part 2 · Section 5

What you do this week

Ten steps in the Request Builder, then the practice set.

Part 3 · Section 6

Optional deep dive

Why the six parts exist: six problems from Morse to JSON.

01A Face With No Brain

Last week your UI took the workflow of Aarav, your first customer, and handed it straight back. Type "I open Jira, read the week's tickets, write a status report and post it on Slack", and it returns the same words. It has a face and no brain.

The brain you want is a model that reads the workflow and writes a plan. That model does not live inside your page. It lives on another machine, owned by someone else. So the question is: how does your UI talk to a machine it has never met?

Input

Aarav's workflowtyped into your UI

→

Process

A modelon someone else's machine

→

Output

A diagnosisback in your UI

The arrow in the middle is the second interface. The first was the UI, between a person and a machine. The second is between two machines: the API.

02Round Three: The Machine That Answers in Codes

Round Three is a game you can replay with a friend playing the machine. Picture a machine that stays silent: every attempt fails without a clue. Now let it answer every message with a number and at most five words. That one change means every failure carries information.

The task: Aarav has built a Diagnosis Service. It turns a description of a workflow into a diagnosis. Get a diagnosis of Aarav's Friday report. Instructions only through a group chat, one line per message. The machine does not guess.

Here is what the machine replied in one run of the game, and what each reply forced the players to add:

Reply	What had been sent	The part it forced
429 Too many requests. One sender.	Several people typing at once	One point of contact
404 Not found. Doors: /aarav/workflows /aarav/diagnoses	No address, or the wrong one	address
400 Which action? CREATE READ UPDATE DELETE	A sentence describing the wish, with no action named	action
405 This door takes CREATE, READ	An UPDATE or DELETE sent to the diagnosis door	action
200 [] Nothing to read yet	A READ for a diagnosis that did not exist yet	Read only fetches what already exists
401 Who are you? Key needed	No key	key
401 Key leaked. Revoked.	The key pasted in the public chat	Keys are secrets and travel privately
400 Can't read. Send {"workflow": "..."}	The workflow as a plain sentence	package in an agreed format
201 Created	Everything right, sent by DM	Done: a diagnosis came back

Three of those replies deserve a second look.

Where did the address come from? Nobody was given it. The first message without one came back 404 with a list of doors. The machine itself told you where to knock.

The 200 that gave you nothing. Reading the diagnoses before any existed came back 200 with an empty list. The request was understood. It was the wrong request. A 200 means "your request was fine", not "you got what you wanted".

The leaked key. The key was handed out privately, by DM. The winning message had to carry it, so the winning message had to travel privately too. A private channel for the key is exactly what the S in HTTPS gives you on the web.

The winning message, sent by DM:

ActionCREATE

Address/aarav/diagnoses

Keykey: ••••••••

Package{"workflow": "I open Jira, read the week's tickets, write a status report and post it on Slack. About 90 minutes."}

And the machine replied:

201 Created · the diagnosis

Repeated pattern: a weekly status report. Bottleneck: reading every ticket to find what changed. First AI step: draft the report from a Jira export; Aarav edits and posts it.

Nobody listed these parts before the game. The machine's replies did, one at a time.

03The Six Parts, Named

After the game, each reply was connected back to a part of the message. Draw the letter again: everything on it now has a name.

AddressWhere it goes · the URL

ActionWhat you want done · the method

KeyWho you are · a header, written on the envelope

PackageThe letter inside · the body, in an agreed format

CodeHow it went · the status code on the reply

Part	In the game	Its name on the web
address	`/aarav/diagnoses`	URL, or endpoint. The domain names the machine; the path (`/aarav/diagnoses`) names the door
action	CREATE, READ, UPDATE, DELETE	Method: POST, GET, PUT or PATCH, DELETE
key	`key: ••••`	A header: `Authorization: Bearer <key>`. "Bearer" means whoever bears this key is let in
package	`{"workflow": "..."}`	The body, written in JSON
code	429, 404, 400, 405, 401, 201	Status code
package back	The diagnosis	The response body

Everything on that envelope together is an HTTP API request. You may have heard the word API before. In this lesson you open it.

The same two principles hold. Input → Process → Output: the request is the input, the machine at the other end is the process, the reply is the output. An interface is a common language plus a protocol: JSON is the common language for the package; HTTP is the protocol for everything around it.

04The CRUD Quiz: Create, Read, Update, Delete

The game's actions were four words. They are the four things you can do to anything stored: Create, Read, Update, Delete, or CRUD. On the wire, each is spelled as an HTTP method.

Aarav's action	CRUD	Method and address
Opens the page listing his past diagnoses	Read	GET /diagnoses
Submits his Friday workflow for the first time	Create	POST /workflows
Fixes one field: "weekly" becomes "every Friday"	Update	PATCH /workflows/7
His UI resends the whole workflow with the fix	Update	PUT /workflows/7
Removes an old workflow	Delete	DELETE /workflows/7

PUT and PATCH are both Update. PUT replaces the whole thing; PATCH changes part of it.

Google search versus asking an LLM

Search for something on Google and look at the address bar: google.com/search?q=…. That is a GET. Ask ChatGPT the same thing, or call a model through an API, and the request is a POST. Why is one a Read and the other a Create?

Google is reading. The pages it searches already sit in its index, and your search fetches results from what is already there. Your question fits in the address, and nothing new is stored.

The model is creating. Your message and a new reply are added to the conversation, and that reply did not exist before you asked. Ask the same question twice and you get two different replies. Your prompt also travels as a package in the body, because it can be long and private, and an address is neither. So generation is a Create, and Create is spelled POST.

The rule

Read what already exists: GET, and nothing changes. Create something new: POST. Update it: PUT or PATCH. Delete it: DELETE.

Companies do not always follow the convention. For any app, its real traffic is the truth. You will read real traffic yourself in step 7 of the Request Builder.

05What You Do This Week

Sections 1 to 4 stopped at the parts. Now you send real requests yourself, in the browser. Do the steps in order; each one has a checkpoint.

Read: your first GET, and the space. The address bar is already an API tool. You will also see why a space becomes %20, and why a raw space causes a 400.
Create: send a package. A POST carries a body. Why does the body need a header that says it is JSON? Because JSON is a format both sides must agree on, and the machine does not guess the format.
Replay Round Three for real. The machine from the game is real. Create a key, then Create a diagnosis, and get the same 201.
Break it on purpose. Cause a 400, 401, 404 and 405 yourself, and note which part each one points to.
Whose fault: every code. The first digit tells you before anything else: 2xx worked, 4xx you sent something wrong, 5xx their machine failed.
Read real traffic. Open DevTools and find the six parts in requests you just sent, then in ChatGPT's.
Put a model behind it. Send Aarav's workflow to a model on Groq. Send the same request twice. Aarav's service gave the same diagnosis twice; the model will not. The door is deterministic; what comes through it is probabilistic. Which answer is right, and who decides?
Find your key, and where it should live. Your key is visible in DevTools. That is why keys live in a backend, never in a page.
Design your API. Write Aarav's table for your own app, then do the practice set.

Checkpoint · steps 1 to 8

Build guide

Milestone: steps 1 to 8 done and a draft of your API table. The question template, checklist and what to have ready are on the troubleshooting page.

Before the next lesson

Practice set

Collect what the steps produce.

Next · Building APIs and the backend

Build the backend

A raw request from your Gradio chat to the model, in Python.

06Optional Deep Dive: Why These Six Parts?

Round Three showed that the parts exist. It did not show why. Each part is there because an earlier system failed in a specific way: a wire that is only on or off (Morse code), machines without a human operator (ASCII), a million machines and lost messages (TCP/IP gave the address), a machine that does not know what you want (HTTP gave the action, the key and the code), fifty companies with fifty verb lists (REST gave nouns and CRUD), and two programs in different languages (JSON gave the package). The Wire lets you work through each problem before you see its answer. It takes about 20 minutes and is not required for the practice set.

07Words You Met

APIThe interface between two machines: a common language plus a protocol.

RequestAddress, action, key, package.

ResponseCode and package.

URL / endpointThe address: the machine (domain) and the door (path).

MethodHow the action is spelled: GET, POST, PUT, PATCH, DELETE.

CRUDCreate, Read, Update, Delete: the four actions on anything stored.

HeaderA line written on the envelope, read without opening the letter. The key goes here.

BearerWhoever bears this key is let in. Written as Authorization: Bearer <key>.

BodyThe package inside the envelope.

JSONA text format, not a language: keys and values in curly braces.

Status codeThree digits on the reply. 2xx worked, 4xx yours, 5xx theirs.

HTTPSHTTP in a sealed envelope, so nobody on the way can read your key.

RESTA design style: nouns as addresses, CRUD as verbs. Not a protocol.

BackendThe machine between your UI and everything else. It holds keys and stores data.

Four things in, two things out.Every system you connect for a customer will speak in these six parts.
Companion pages: Request Builder · practice set · troubleshooting · kit