What Is a REST API?

1. What "REST" actually stands for

REST stands for Representational State Transfer — a name that explains almost nothing on first read. It was coined by Roy Fielding in his 2000 doctoral dissertation, as a description of the architecture the web itself already used successfully: resources identified by URLs, manipulated through a small, fixed set of HTTP methods.

In practice, "REST API" has come to mean something simpler than the formal definition: an API where you interact with named things (resources) at predictable URLs, using standard HTTP verbs, and get structured data back. That's the 95% version almost every public API you'll encounter actually implements — including nearly every one in our catalog.

2. Everything is a resource

A resource is any "thing" the API lets you work with — a user, an order, a photo, a weather station, a repository. Each resource type gets its own URL pattern, and each individual resource gets its own address within that pattern:

Notice the pattern: plural nouns for collections (/repos), an ID to pick one item out of the collection (/repos/42), and nesting to express relationships (/repos/42/issues — "the issues that belong to repo 42"). This is the single most consistent convention across REST APIs, and once you can read it, you can guess your way around an API you've never used before.

3. HTTP verbs: what you can do to a resource

Where the URL says what you're operating on, the HTTP method says what you're doing to it. REST reuses the same small set of verbs for every resource type instead of inventing a new action name per endpoint — that's most of what makes REST predictable to learn.

"Safe" means the call doesn't change anything on the server — you could retry it, cache it, or have a search-engine crawler follow it, and nothing bad happens. "Idempotent" means calling it once has the same effect as calling it five times in a row: deleting resource 42 twice still just leaves it deleted. POST is neither — calling it twice typically creates two resources, which is exactly why browsers warn you before resubmitting a form.

4. Why REST is "stateless"

In a stateless API, the server keeps no memory of your previous requests. Every single request has to carry everything the server needs to understand it — your credentials, the resource you want, any filters — because the server treats each call as if it's the first one it's ever seen from you.

This is also why almost every authenticated REST request includes the same Authorization header or API key on every single call, rather than logging in once and being remembered — see our guide to API keys for how that credential actually travels with the request.

5. A real worked example

Let's trace an actual sequence of calls against a real, free, public REST API — GitHub's. No key required for public read-only data.

1. List a user's repositories — a GET against a collection:
   GET https://api.github.com/users/octocat/repos
2. The response is a JSON array — one object per repository:
   [ {
     "name": "Spoon-Knife",
     "full_name": "octocat/Spoon-Knife",
     "stargazers_count": 15234,
     "language": "HTML"
     }, …
   ]
3. Drill into one repository by adding its identifier to the URL — the collection/individual-resource pattern from section 2:
   GET https://api.github.com/repos/octocat/Spoon-Knife
   This time the response is a single JSON object, not an array — one resource, not a collection of them.
4. Go one level deeper into that repository's issues — a nested collection, exactly as described in section 2:
   GET https://api.github.com/repos/octocat/Spoon-Knife/issues

Notice that all four calls used GET — read-only, safe to retry, cacheable. Creating a new issue would be the exact same URL as step 4, but a POST instead, with the issue title/body sent as the request body rather than in the URL. Same resource, different verb, different meaning — that's the whole REST idea in one example.

6. Conventions you'll see everywhere

Pagination

Collections with thousands of items are never returned all at once. Most REST APIs accept ?page=2 or ?limit=50&offset=100 query parameters, and many return a Link header or a next field in the JSON body pointing you to the next page.

Filtering & sorting

Query parameters narrow a collection without changing the URL structure: /repos?language=JavaScript&sort=stars. This keeps the resource path stable (still "the repos collection") while letting you ask a more specific question of it.

Versioning

APIs change over time, and breaking every existing integration isn't an option — so most REST APIs version themselves, either in the URL (/v2/repos) or in a request header (Accept: application/vnd.github.v3+json). If a page in our catalog mentions a version number in its base URL, that's what it's for.

Errors are just resources with bad news

A well-designed REST API doesn't return 200 OK with an error message buried in the body — it uses the HTTP status code itself (404 for "that resource doesn't exist," 422 for "your data didn't validate") with a JSON body explaining why, so you can handle failures programmatically without parsing English text.

7. REST vs. GraphQL vs. SOAP

REST isn't the only way to build an API — it's just the most common one for public, free APIs, which is why it's the default assumption in this guide and across our catalog. Two alternatives worth knowing by name:

If an API page doesn't say otherwise, assume REST — it's overwhelmingly the default for the free and public APIs indexed on this site.

Continue learning