Skip to content
Happy Programming Guide
Start learning
Web Development

REST APIs for Beginners

What a REST API is, how resources, methods and status codes fit together, a real request and response walked through, and how to call and build one.

A circuit board with a broken capacitor

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.

Output
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#

Output
GET /books/42 HTTP/1.1
Host: api.example.com
Accept: application/json
Authorization: Bearer eyJhbGci...
Output
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#

Output
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#

Terminal
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}'
JavaScript
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 }),
});
Python
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:

Python
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#

How HTTP works, for beginnersRead next

Keep reading

Keep going — pick your next guide

The fastest way to improve is to read one guide, then build the thing it describes. Start with the basics, or jump straight to a project.

Ask a question or share what worked

Your email address will not be published. Required fields are marked *