A REST API is a way for programs to talk to each other over HTTP using the same conventions the web already uses: URLs name things, HTTP methods say what to do with them, and status codes say how it went. If you can open a web page, you already understand half of it. This article covers the conventions, walks through a real request and response, and shows how to call an API and how to build a small one.
The idea#
An API is a set of URLs a program can request. REST is a style for designing those URLs so they are predictable: every URL represents a resource, a thing you might want to read or change, and the HTTP method says what you want to do with it.
GET /books list the books
POST /books create a book
GET /books/42 read book 42
PUT /books/42 replace book 42
PATCH /books/42 change part of book 42
DELETE /books/42 delete book 42
Six lines, and you can guess the rest of the API. That predictability is the entire point. URLs are nouns; the method is the verb. An API with /getBook and /deleteBook endpoints is not following the convention, and it is harder to learn for exactly that reason.
A real request and response#
GET /books/42 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGci...
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": 42,
"title": "The Pragmatic Programmer",
"year": 1999,
"available": true
}
The request has a method, a path, and headers; this one says it wants JSON and includes a token proving who is asking. The response has a status code, headers, and a body, almost always JSON. That is the whole exchange, and every REST call looks like it.
Methods and what they promise#
| Method | Use | Safe? | Repeatable? |
|---|---|---|---|
| GET | Read | Yes: changes nothing | Yes |
| POST | Create, or an action that does not fit elsewhere | No | No: twice creates two |
| PUT | Replace the whole resource | No | Yes: twice has the same effect as once |
| PATCH | Change some fields | No | Usually |
| DELETE | Remove | No | Yes |
“Repeatable” is idempotence: a client that retries a PUT or DELETE after a network failure does no extra harm, while retrying a POST might create a duplicate. That distinction is why the methods exist rather than everything being POST.
Status codes#
The first digit tells you the category: 2xx worked, 4xx you did something wrong, 5xx the server did. The ones you will see constantly:
- 200 OK, with a body. 201 Created, after a POST. 204 No Content, after a DELETE.
- 400 Bad Request: malformed or invalid. 401 Unauthorized: not logged in. 403 Forbidden: logged in, not allowed. 404 Not Found. 429 Too Many Requests.
- 500 Internal Server Error. 503 Service Unavailable.
A good API uses them precisely, and a client should check them before reading the body.
Query parameters#
GET /books?author=hunt&sort=year&page=2&limit=20
Filtering, sorting and paging go in the query string. The path identifies the collection; the parameters refine it. Anything after the ? is optional by convention.
Calling an API#
curl -s https://api.example.com/books/42 -H "Accept: application/json"
curl -s -X POST https://api.example.com/books \
-H "Content-Type: application/json" \
-d '{"title": "Clean Code", "year": 2008}'
const res = await fetch('https://api.example.com/books/42');
if (!res.ok) throw new Error('HTTP ' + res.status);
const book = await res.json();
await fetch('https://api.example.com/books', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ title: 'Clean Code', year: 2008 }),
});
import requests
r = requests.get("https://api.example.com/books/42", timeout=10)
r.raise_for_status()
book = r.json()
requests.post("https://api.example.com/books", json={"title": "Clean Code", "year": 2008}, timeout=10)
Three languages, one shape: method, URL, headers, body, then check the status and parse the JSON.
Authentication#
Most APIs need to know who is calling. The common forms: an API key in a header, a bearer token from a login step, or OAuth for acting on behalf of a user. All of them are a header on every request, and none of them belong in the URL or in code you commit. Put keys in environment variables.
Building one#
Every web framework makes this short. In Python with FastAPI:
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
app = FastAPI()
books = {42: {"id": 42, "title": "The Pragmatic Programmer", "year": 1999}}
class BookIn(BaseModel):
title: str
year: int
@app.get("/books/{book_id}")
def read_book(book_id: int):
if book_id not in books:
raise HTTPException(404, "Book not found")
return books[book_id]
@app.post("/books", status_code=201)
def create_book(book: BookIn):
new_id = max(books) + 1
books[new_id] = {"id": new_id, **book.model_dump()}
return books[new_id]
The conventions that make an API pleasant to use are the ones above: plural nouns for collections, ids in the path, JSON in and out, the right status code for each outcome, and one consistent shape for errors.
Questions people ask#
Is REST a protocol?
No. It is a set of conventions on top of HTTP. There is no specification to comply with, which is why APIs vary in how closely they follow it.
What is the difference between REST and an API?
API is the general term for any programmatic interface. REST is one style of web API; GraphQL and gRPC are others.
Do I need JSON?
Almost universally, yes. XML is still seen in older systems.
What does stateless mean?
Each request carries everything the server needs, including authentication; the server does not remember previous requests. It is what lets an API scale across many servers.
Where to go next#
- What is an API? — the broader idea.
- Build a REST API with FastAPI — the full project.
- How HTTP works — the protocol underneath.