Module 2: REST Principles

Introduction to Module 2: REST Principles

Overview

In Module 1 you learned the HTTP protocol: requests, responses, methods, status codes, headers. You know how to send a request and read the response. But HTTP only gives you the how — it doesn't tell you how to organize your URLs, when to use each method, or what structure to give your API so other developers understand it without reading documentation.

REST (Representational State Transfer) is the architecture that solves that. REST takes HTTP and gives it meaning: resources are nouns (/users, /products), methods are verbs (GET = read, POST = create), and URLs follow predictable patterns. When an API follows REST, any developer can infer how to use it: "if /users exists, /users/1 surely gives me the user with ID 1."

This module teaches you to think in REST. By the end, you'll be able to evaluate whether an API is well designed, consume it following its conventions, and design your own endpoints for when you build APIs with FastAPI. The difference between a developer who "makes requests" and one who "understands APIs" is exactly what this module covers.

Where are we in the guide?

Context within the guide

Module 1: HTTP Protocol Fundamentals ✅ Completed
    You learned: requests, responses, methods, status codes, headers
    ↓
Module 2: REST Principles ← You are here
    You'll learn: resources, URIs, CRUD, API design
    ↓
Module 3: JSON & Tools
    You'll learn: serialization, validation, Postman
    ↓
Module 4: Consuming Public APIs (Capstone Project)
    You'll build: REST Client CLI with 5+ APIs

Progression within the guide

Module 1: Understand the PROTOCOL          → HTTP (the infrastructure)
Module 2: Learn the CONVENTIONS            → REST (the architecture) ← YOU ARE HERE
Module 3: Master the FORMAT AND TOOLS      → JSON + Postman (the ecosystem)
Module 4: INTEGRATE it all in a project    → REST Client CLI (the practice)

Connection to Module 1

The transition from Module 1 to Module 2 is direct: "you already know the protocol at a low level → now learn the conventions that make APIs predictable and professional."

What you learned in M1	How it's used in M2
HTTP methods (GET, POST, PUT, DELETE)	They map to CRUD operations on resources
Status codes (200, 201, 404, 500)	They're used consistently based on the REST operation
Headers (Content-Type, Accept)	They define the format contract between client and server
URLs and paths	They become URIs that represent resources
Request/Response cycle	It gets structured into predictable, repeatable patterns

Module 1 gave you the pieces. Module 2 teaches you how to assemble them into something coherent.

The leap: from "making requests" to "understanding APIs"

Without REST: HTTP as a generic tool

Imagine you're consuming an API with no REST conventions. The endpoints look like this:

POST /api/getUsers              → Get the list of users
POST /api/getUserById            → Get one user (ID in the body)
POST /api/createNewUser          → Create a user
POST /api/updateUserInformation  → Update a user
POST /api/removeUser             → Delete a user

Everything is POST. The endpoint names are long verbs. To know what each one does, you need to read the full documentation. And every new API you consume has a different structure — no patterns, no predictability, no way to infer anything.

This isn't hypothetical. APIs like this exist (plenty of legacy APIs work exactly like that). And consuming them is slow and frustrating because every endpoint is a surprise.

With REST: HTTP with meaning

The same API, designed with REST principles:

GET    /users          → Get the list of users
GET    /users/42       → Get the user with ID 42
POST   /users          → Create a new user
PUT    /users/42       → Update the entire user
PATCH  /users/42       → Update specific fields
DELETE /users/42       → Delete the user

Without reading any documentation, a developer who knows REST can infer:

"If there's /users, there's probably /users/{id} for a specific user."
"GET to read, POST to create, PUT/PATCH to update, DELETE to remove."
"If I need a user's posts, it's probably /users/42/posts."

That ability to infer an API's structure without documentation is what REST gives you. And it's why 90% of modern APIs (GitHub, Stripe, Twitter, OpenAI) follow REST.

The difference in speed

Without REST:
1. Receive the API documentation           → 10 minutes
2. Read every endpoint                     → 20 minutes
3. Understand each request's structure     → 15 minutes
4. Start consuming                         → 45 minutes later
5. Every new API: repeat from step 1

With REST:
1. See the base URL and one endpoint       → 1 minute
2. Infer the rest of the endpoints         → 2 minutes
3. Verify with 2-3 test requests           → 3 minutes
4. Start consuming                         → 6 minutes later
5. Every new REST API: same patterns

REST isn't just an elegant convention — it's a time investment that pays off with every API you consume after you learn it.

Preview: REST in action

Here's a concrete example of what REST principles look like applied to a real domain. Suppose you're designing an API for a task system (a todo app):

The resources

Main resource: Task
Secondary resource: Category
Relationship: each Task belongs to a Category

The REST endpoints

Tasks:
GET    /tasks              → List all tasks
GET    /tasks/7            → Get the task with ID 7
POST   /tasks              → Create a new task
PUT    /tasks/7            → Update the entire task
PATCH  /tasks/7            → Mark as completed (a single field)
DELETE /tasks/7            → Delete the task

Categories:
GET    /categories         → List categories
GET    /categories/3       → Get category 3
POST   /categories         → Create a category

Relationships:
GET    /categories/3/tasks → Tasks in category 3

Filtering and pagination:
GET    /tasks?status=pending          → Pending tasks
GET    /tasks?category_id=3&sort=date → Tasks in category 3, sorted by date
GET    /tasks?page=2&per_page=10      → Page 2, 10 per page

In Python

import requests

BASE = "https://api.example.com/v1"

tasks = requests.get(f"{BASE}/tasks").json()

new_task = requests.post(f"{BASE}/tasks", json={
    "title": "Learn REST",
    "category_id": 3
}).json()

requests.patch(f"{BASE}/tasks/{new_task['id']}", json={
    "completed": True
})

pending = requests.get(f"{BASE}/tasks", params={
    "status": "pending",
    "sort": "created_at"
}).json()

The patterns are predictable, consistent, and reusable. That's REST.

Module objective

By the end of this module, you'll be able to:

✅ Identify resources in any domain (users, orders, products, posts)
✅ Design RESTful URIs: plural nouns, IDs in the path, no verbs in the URL
✅ Map CRUD operations to HTTP methods correctly
✅ Understand idempotency and statelessness — and why they matter
✅ Apply API versioning (URL vs header)
✅ Design pagination and filtering
✅ Evaluate whether a real API follows REST best practices
✅ Write a REST API design document for a domain

Professional objective

After this module, when someone hands you a new API, your first thought will be "what resources does it expose?" and "what operations does it support?" — not "where's the documentation?". That resource mindset is what separates a developer who consumes APIs with confidence from one who uses them with fear.

Prerequisites

Required knowledge

Module 1 completed: understanding requests, responses, HTTP methods (GET, POST, PUT, PATCH, DELETE), status codes, headers
Python with requests: knowing how to make HTTP requests with the requests library
Basic JSON: reading and manipulating JSON objects

Quick check

Answer these questions:

Can you explain the difference between GET and POST?
Do you know what a 404 status code means? And a 201?
Can you make a requests.get() with custom headers?

If you answered "yes" to all 3, you're ready. If any of them gives you pause, revisit the corresponding capsules from Module 1.

Technical setup

Reuse the environment from Module 1:

# Activate your virtual environment
cd rest-apis-guide
source venv/bin/activate  # Mac/Linux

# Verify that requests works
python -c "import requests; print('requests OK')"

# Create a folder for this module
mkdir -p module-02

You don't need to install anything new for this module. The exercises use requests (which you already have) and public APIs.

APIs you'll use in the exercises

API	Base URL	Auth
JSONPlaceholder	`https://jsonplaceholder.typicode.com`	No auth
GitHub API	`https://api.github.com`	Token optional
Dog CEO	`https://dog.ceo/api`	No auth

These APIs are free and require no signup (GitHub works without a token for public endpoints).

Module roadmap

Capsule	Topic	What you'll learn
01	Module introduction	Context, objectives, roadmap ← You are here
02	Resources and URIs	Resources as nouns, designing predictable URLs
03	CRUD and HTTP methods	Mapping CRUD operations to HTTP methods
04	Idempotency and statelessness	REST's key properties and why they matter
05	API design	Naming conventions, good and bad practices
06	Versioning and pagination	Versioning, pagination, filtering, sorting
07	Real-world APIs: analysis	Evaluating GitHub, JSONPlaceholder and OpenWeather as REST APIs
08	Project: REST API design doc	Designing the endpoints of a complete API

Learning flow

Resources and URIs (02)
  "What are resources? How do I design URLs?"
    ↓
CRUD + methods (03) + Idempotency (04)
  "What operations exist? What properties do they have?"
    ↓
API design (05) + Versioning/pagination (06)
  "How do I design a professional API?"
    ↓
Real-world APIs (07) + Project (08)
  "How do real APIs apply these principles?"

First you understand the concepts (resources, CRUD, properties), then you apply the design conventions, and finally you analyze real APIs and design your own.

Estimated module duration: 4-5 hours (readings + exercises + project).

An analogy: REST as a library system

If REST feels abstract, think about a library:

LIBRARY                             REST API
───────                             ────────
Resources = books, authors,         Resources = users, products,
            members, loans                      orders, reviews

Organization:                       URIs:
  Section → Shelf → Book              /authors → /authors/42 → /authors/42/books

Operations:                         HTTP methods:
  Search the catalog = read           GET = read
  Register a new book = create        POST = create
  Update the details = modify         PUT/PATCH = update
  Retire a book = remove              DELETE = delete

Rules:                              REST principles:
  Every book has a unique code        Every resource has a unique ID
  The code never changes              The URI is stable
  Searching changes nothing           GET is idempotent and safe
  The catalog is organized            URIs are predictable

A well-organized library lets you find any book in minutes, even without the librarian's help. A well-designed REST API lets you consume it in minutes, even without detailed documentation. Predictable organization is REST's fundamental value.

Connection to the guide's project

The REST Client CLI from Module 4 consumes APIs that follow REST: JSONPlaceholder (/posts, /users, /comments), GitHub (/repos, /users), OpenWeather. Without understanding REST, your CLI would be code that works by accident. With REST, you can:

Predict endpoints without documentation (/users/1/posts → user 1's posts)
Use the right method for each operation (GET to read, POST to create)
Handle pagination (?page=2&per_page=10) in APIs that return many results
Interpret responses based on conventions, not trial and error

The module project: REST API design doc

In capsule 08, you'll pick a domain (online store, social network, booking system) and design all its REST endpoints: resources, URIs, methods, request bodies, response formats, status codes, pagination and versioning. It's a design exercise, not a coding one — and it's exactly what you'll do before building a real API with FastAPI.

What this module does NOT cover

❌ Building APIs — This module is about principles and design. Building APIs with code is the FastAPI Fundamentals guide (#6).
❌ GraphQL, gRPC, WebSockets — They're alternatives to REST, and they're not covered in this foundational guide.
❌ Advanced authentication — OAuth2 and JWT in depth come later in the path.
❌ HATEOAS in depth — We mention it as a concept, but it isn't common in practice and you don't need it right now.
❌ OpenAPI/Swagger — API documentation tools are covered in the FastAPI guide.

REST is not dogma

One important point before we start: REST has principles, not absolute laws. You're going to find APIs that don't follow REST 100% — and that's fine. Some APIs use POST for everything, others put verbs in the URL, others don't version at all.

Your job isn't to be a purist. Your job is to:

Know the conventions so you can apply them when you design
Recognize the patterns so you can consume any API fast
Adapt when an API doesn't follow the principles to the letter

The capsules in this module give you the principles AND show you how the industry applies them (or doesn't) in practice.

Troubleshooting

"Is REST a standard or a convention?"

REST is an architectural style, not a formal standard like HTTP or SQL. There's no "REST committee" that approves or rejects APIs. There are principles documented by Roy Fielding in his doctoral dissertation (2000), and the industry adopted them as conventions. That means there's flexibility — but it also means every team can interpret REST differently.

"Are all APIs REST?"

No. There are SOAP APIs (XML-based, common in enterprise legacy), GraphQL (Facebook's query language), gRPC (Google's Protocol Buffers), and generic RPC APIs. But REST dominates today's web ecosystem. GitHub, Stripe, Twilio, OpenAI — they all use REST. Learning REST first covers 90% of the APIs you'll consume.

"Are REST and RESTful the same thing?"

Technically, "REST" is the architecture and "RESTful" is the adjective for describing APIs that follow that architecture. In practice, they're used interchangeably. When someone says "REST API" or "RESTful API", they mean the same thing.

"Can I design a good API without knowing REST?"

You can, but you'll reinvent the wheel. REST gives you conventions proven by 20+ years of massive use. Without REST, you make every design decision (how do I name the endpoints? which methods do I use? how do I paginate?) from scratch. With REST, most of those decisions are already solved.

"Why does idempotency matter if I'm only going to consume APIs?"

Because it affects how you handle retries. If a request fails and you need to send it again, you need to know whether that's safe. A GET is idempotent — you can resend it with no consequences. A POST isn't — resending it could create a duplicate resource. That distinction saves you from subtle bugs.

Success criteria

By the end of this module, you'll know you succeeded if:

✅ You can identify a domain's resources (e.g. "an online store has users, products, orders, reviews")
✅ You can design RESTful URIs for those resources (/products/42/reviews)
✅ You can explain why /getUsers is bad practice and /users is correct
✅ You can map CRUD to HTTP methods without hesitating
✅ You can analyze a real API and evaluate how well it follows REST
✅ Your API design document has clear, consistent, predictable endpoints

Quick self-assessment test

By the end of the module, you should be able to answer:

What is a resource in REST? Give 3 examples from your favorite domain.
What's the correct URI to get post #5 from user #42?
What HTTP method would you use to change only a user's email?
What does it mean that GET is idempotent and safe?
Why is a stateless API more scalable than a stateful one?
What's the difference between versioning by URL (/v2/users) and by header?

If you can answer all 6 with confidence, you've mastered REST.

Summary

REST is the architecture that gives structure to HTTP — resources as nouns, methods as verbs
The ability to infer an API's structure without documentation is what REST gives you
This module turns "I know how to make requests" into "I know how to design and consume professional APIs"
You'll learn resources, URIs, CRUD, idempotency, statelessness, versioning, pagination
All of it applies directly in the REST Client CLI from Module 4
REST has principles, not laws — pragmatism matters more than purism
The module's final project is a complete REST API design document

Additional resources

If you want some context before starting (optional):

REST API Tutorial - Complete reference of REST principles
MDN: An Overview of HTTP - HTTP refresher (REST's foundation)
Roy Fielding's Dissertation (Chapter 5) - The original paper that defined REST
GitHub REST API Documentation - Example of a well-documented REST API
JSONPlaceholder - Test REST API you'll use in the exercises
Best Practices for REST API Design - Practical article from Stack Overflow

Next capsule: Resources and URIs — you'll learn to think in terms of resources (nouns) and design predictable URLs that any developer can understand.

← PreviousModule 1 project: HTTP Explorer Next →Resources and URIs: the vocabulary of REST