REST APIs, Explained

You've called REST APIs. You've sent a GET to fetch some users, POSTed a form, maybe seen a 404 and sighed. But "REST" itself has probably stayed a fuzzy word - something everyone says, nobody defines, and that somehow describes most of the APIs you'll ever touch.

Here's the relief: REST is not a framework, a library, or a magic protocol. It's a small set of ideas about how to lay an API out - things live at addresses, and you act on them with a fixed handful of verbs. Once those ideas click, you can read almost any web API on sight, and design one that other people can read too.

How to read this

• Need a quick reference? Phase 1 has the resource-and-method grid, and Phase 2 has the status-code and convention cheat sheet - both are scannable on their own.
• Want REST to finally make sense? Read in order. Phase 1 installs the mental model, Phase 2 turns it into real endpoints, and Phase 3 tells you the plain truth about where REST strains.

The phases

1. Resources & Verbs - the core mental model: resources live at URLs, HTTP methods are the verbs, and every request is self-contained (stateless).
2. Designing Endpoints - the practical conventions: nouns not verbs, collections vs. items, meaningful status codes, and query params for filtering, sorting, and paging.
3. REST in the Real World - the clear-eyed part: REST is a style, not a law, and the pain points (over-fetching, round trips, versioning) that lead people to other tools.

This guide stays on the dominant request/response style. GraphQL - a different answer to REST's pain points - gets its own home in GraphQL, Explained, and the deeper craft of evolving an API safely lives in Designing APIs That Last.