← Systems

API Fundamentals

Verified Sep 11, 2026

The big picture — click a piece to jump to it

  • An API call is three things: an endpoint (where), a method (what to do), and a status code (what happened).
  • The endpoint names a resource, not an action — the method is the verb that acts on it.
  • The status code is the real answer. The body is detail — check the code first, always.

01 · WHERE

Endpoint

A street address for one specific thing, not a command — /todos/2 names todo #2. It doesn't say what to do with it.

Real-world example

/todos names "the todos" as a group; /todos/2 names one specific todo. Same noun, more specific address — that's the whole pattern most REST APIs use.

Under the hood

An endpoint is a URL path a server's router matches against — the same matching idea as Tech Stack Fundamentals' route table, just with no method baked in yet.

Where AI fits in

A tool schema an agent calls is, underneath, an endpoint plus a method — the agent is choosing both when it decides which "tool" to use.

02 · WHAT

Method

The verb next to the address. GET reads, POST creates, PUT replaces, DELETE removes — same endpoint, different method, a completely different outcome.

Real-world example

GET /todos/2 reads it. DELETE /todos/2 removes it. Same address — try both in the live lab below.

Under the hood

GET is meant to be safe — it shouldn't change anything. That's why a browser can prefetch or cache a GET without asking, and never a POST.

Where AI fits in

An agent wired with only GET-shaped tools genuinely can't corrupt your data, no matter what it decides — the method is the real safety boundary, not a prompt instruction telling it to "be careful."

03 · OUTCOME

Status code

A 3-digit answer sent back with every single response, no exceptions. 2xx it worked, 4xx you made a mistake, 5xx they did.

2xx — Success

The request was received, understood, and acted on. 201 Created — POST /todos just made a new one.

4xx — Client error

The request itself was the problem -- bad input, wrong path, no permission. 404 Not Found — that id was never real.

5xx — Server error

The request was fine; the server broke while handling it. 500 Internal Server Error — a bug on their end, not yours.

Where AI fits in

An agent parses the status code programmatically, not the wording of the body — a confidently worded error message doesn't change that 500 means "retry," not "trust this."

See it happen — live

todos-api.sima genuinely real (tiny) in-memory REST API — build a request, send it, see what actually comes back
Method
GET
Request
— nothing sent yet —
Response

—

Common misconceptions
  • "A 404 means the whole API is down." It means that one resource wasn't found — every other endpoint is unaffected. Try GET /todos/999 above, then GET /todos right after.
  • "GET is just as safe to skip checking as any other method." Backwards — GET is the one method that's supposed to be side-effect-free, which is exactly what makes it safe to cache, retry, and prefetch.
  • "REST means JSON." REST is a style, not a format — JSON just won out as the common choice. The endpoint/method/status-code shape here works the same with XML or anything else.
Go deeper