Lesson 18.0

Orientation: every API is a contract

Artifact: A one-paragraph definition of API and the six shapes you'll meet

1. The promise

You'll define an API in one sentence. You'll name the six API shapes this chapter covers. You'll say what problem each one is shaped for. That's the whole orientation.

2. The mental model

An API (application programming interface) is a written agreement between two programs. The two programs don't have to live on the same machine. They don't have to be written in the same language. They don't have to be owned by the same team. They only have to agree on the contract.

Picture a restaurant menu. The menu doesn't tell you how the kitchen works. It tells you what you can order, what you'll get back, and how to ask for it. The kitchen can swap chefs, change ovens, or move buildings. The menu still works.

(SCREENSHOT: a restaurant menu next to a kitchen order ticket — staged photo or stock image — used as the contract analogy)

(DIAGRAM: the six API shapes side by side — annotated SVG — six labelled boxes (REST / GraphQL / tRPC / WebSocket / SSE / Webhook) with a one-line use case under each)

The six shapes this chapter covers:

  • REST — HTTP verbs against URL resources. The default for public web APIs.
  • GraphQL — one endpoint, a query language, the client asks for exactly what it needs.
  • tRPC — function calls across a network, with shared TypeScript types. The default inside a JavaScript monorepo.
  • WebSockets — a connection that stays open. Either side can push messages.
  • SSE (server-sent events) — a one-way stream from the server to the browser over plain HTTP.
  • Webhooks — the third party calls you when something happens.

You don't need all six on day one. You'll pick one for each problem and live with the choice for years.

3. You do it, with me

There's nothing to install in this unit. Read along.

Open the course chapter index in your browser.

(SCREENSHOT: the chapter index for Ch 18 — full window — orientation unit highlighted)

Open a scratch file in VSCode. Call it apis.md. You'll write one line per shape in your own words.

bashterminal — create a scratch file for this unit
mkdir -p ~/click-to-career-bootcamp/ch18
cd ~/click-to-career-bootcamp/ch18
code apis.md

Write six headings, one per shape. Under each heading, write one sentence answering: what problem is this shape for?

Don't look at the answers above. Try first, then read.

4. What you should be seeing

Three things in your head:

  • One sentence. An API is the contract between two programs.
  • Six shapes. REST, GraphQL, tRPC, WebSockets, SSE, webhooks. You can name them without looking.
  • One pick per problem. You won't ship all six in one app. You'll pick the right one for each consumer.

A short note on what's not in this chapter. gRPC turns up in Kubernetes-style service traffic; it's named here but not taught. MQTT runs on IoT devices. AMQP runs on message queues. You'll meet these on the job, and the vocabulary in this chapter transfers.

5. Common stumbles

  • You think "API" and "REST endpoint" mean the same thing. They don't. REST is one shape an API can take. Webhooks are an API. A WebSocket is an API. A tRPC router is an API.
  • You think newer shapes replace older ones. They don't. GraphQL didn't kill REST. tRPC didn't kill GraphQL. Each one is shaped for a different problem.
  • You skip this unit because it's short. The six names recur in every later unit. Pin them now or look them up later.

6. You should know

1/16
Next