APIs API · 00 · 01

Start from zero: what an API actually is

An API is a contract two programs use to talk. This is the from-zero map and the eight words the rest of the track assumes you already know before the senior units begin.

API Foundations ◷ 10 min

Level

FoundationsJuniorMiddleSenior

You open a weather app and it shows today’s forecast. You didn’t write the weather data — nobody expects you to own satellites. Somewhere behind the scenes your app sent a question to a weather company’s computer, and that computer sent back an answer. Neither program cares what language the other is written in, what OS it runs on, or where in the world it lives. They just follow a shared agreement about how to ask and how to answer. That agreement is an API. Everything in this track — REST, status codes, pagination, GraphQL, gRPC, rate limiting — is detail built on top of that one idea. This lesson is the map before the units.

The one problem APIs solve

When you add a payment button, embed a map, or log in with Google, you are relying on someone else’s computer to do work for you — and that computer has never heard of your codebase. APIs are how that works without chaos.

Every non-trivial application needs data or functionality it did not build itself: payment processing, map tiles, user authentication, stock prices, translation. Without a shared agreement, each pair of programs would have to invent its own communication language from scratch. An API solves this by publishing a stable, documented contract: “send me a message in this shape, and I will always answer in that shape.” The caller does not need to know how the other side works internally — only what to ask and what to expect back. That separation is what makes the internet composable: millions of programs talking to millions of others, each knowing only the surface of what it calls.

Everything else in this track is detail on top of that single idea: publish a stable contract, then honor it.

The eight words the rest of the track assumes

The senior lessons that follow drop these terms without stopping to define them. Here they are, one sentence each — what it is and why it exists.

Word	What it is	Why it exists
API	A published contract describing how two programs can talk.	So each side can evolve independently as long as it honors the contract.
Endpoint	A specific URL that represents one resource or action (e.g. `/users/42`).	So each capability has a stable address callers can target.
HTTP method	A verb (GET, POST, PUT, PATCH, DELETE) that says what to do at an endpoint.	So the same URL can mean “read”, “create”, “update”, or “delete” depending on the verb.
Request body	Data the caller sends along with a POST or PUT (usually JSON).	So the server knows what to create or how to update without guessing.
Response body	Data the server sends back (usually JSON).	So the caller receives the result it asked for in a predictable shape.
JSON	A text format for structured data: keys, values, arrays, objects.	So any language can read or write the data without a custom parser.
Status code	A three-digit number (200, 404, 500 …) the server adds to every response.	So the caller knows immediately whether the request succeeded or why it failed.
Resource	A thing the API exposes — a user, an order, a product, a message.	So the API is organized around stable nouns, not around server-side operations.

How they fit together

Read in order, the words tell one story: a client picks an endpoint (a URL naming a resource), chooses an HTTP method (what to do), and optionally sends a request body with the data. The server does the work, then returns a response body — usually JSON — plus a status code that says whether it worked. Both sides agreed in advance on what those shapes look like: that agreement is the API contract. That single paragraph is the entire track in miniature — every later unit zooms into one of those pieces.

The eight words are not a flat list — they group into the two halves of every contract: what the client sends (request) and what the server returns (response).

▸Why this works

Why does any of this need a formal contract? Because programs change. A backend team can rewrite their database from scratch, a frontend team can redesign the whole UI, and as long as both sides still speak the same API, nothing breaks for the other. Without that contract, every change on one side risks silently breaking the other. The contract is not bureaucracy — it is the thing that lets two teams move independently at speed.

You do not need to memorise this

Two honest notes before the units. First: nobody holds all of this at once on day one — you will meet each word again, in depth, in its own unit, and it will stick then. This page is a coat-hook to hang the details on, not a test. Second: not every API uses every word in the same way. REST uses resources and HTTP methods heavily; GraphQL ignores most HTTP methods and uses one endpoint; gRPC skips JSON entirely. The track teaches the full landscape because that is what real systems demand — but “understand the concept, then learn how each style applies it” is itself the senior instinct.

Quiz

What is the job of an HTTP status code?

Order the steps

Order the steps of one API call, from client to response:

1 Client picks an endpoint (URL + resource) and an HTTP method
2 Client sends the request, with an optional JSON body
3 Server processes the request and builds a response
4 Server returns a JSON body and a status code

The status code travels in the response and is the contract's error-signalling layer — clients must read it before trusting the body. A 404 body may be empty or an error object; a 201 body is the created resource. Both sides agreed on those shapes before the call.

Recall before you leave

01
In one breath, what is an API and why does the contract matter?
02
Trace one complete API call, naming each piece.

Recap

An API is one idea with a lot of detail hung off it: publish a contract that says how to ask and how to answer, then honor it, so that the two sides can change independently without breaking each other. The request half is a method (GET, POST, PUT, PATCH, DELETE) aimed at an endpoint (a URL naming a resource), with an optional JSON body carrying the data. The response half is a JSON body plus a status code that says whether it worked. JSON is the universal data format both sides agree on because any language can read it without a custom parser. The endpoint names a resource — a noun like user, order, or product — rather than a server operation, so the API stays stable as the internals change. You do not need to hold all eight words at once — each gets its own unit ahead. Now when you see “the API returned a 404” or “send a POST with a JSON body,” you know exactly which piece of the contract broke down and where to look next.

Something unclear?

Ask a question about this lesson. Questions are anonymous and go straight to the author to make the lesson better.

Apply this

Put this lesson to work on a real build.

Mini CRUD APIBuild your first real backend: a tiny HTTP API that creates, reads, updates, and deletes notes — backed by SQLite so the data survives a restart. You go from a one-line 'hello' server to a small service that validates input and stores rows, one honest step at a time.