REST Principles
What makes an API RESTful — resources, statelessness, uniform interface
Free tier: read the explanation here. Upgrade to Pro for Drills, Speed challenges & Mastery badges.
UpgradeKnowledge Debt detected
You can study this freely — but your score may plateau if these foundations have gaps. The Mastery badge requires them to be solid.
Explanation
REST (Representational State Transfer) is an architectural style for designing APIs. It's not a protocol — it's a set of constraints that make APIs predictable and scalable.
6 REST constraints:
1. Resource-based URLs — URLs identify resources (nouns), not actions (verbs): `` GET /users/42 ✓ (get user 42) POST /getUser ✗ (verb in URL)
2. HTTP methods as verbs:
GET /posts → list posts GET /posts/1 → get post 1 POST /posts → create post PUT /posts/1 → replace post 1 entirely PATCH /posts/1 → partially update post 1 DELETE /posts/1 → delete post 1
3. Stateless — each request contains all information needed. Server holds no session state. Auth token must be sent with every request.
4. Uniform interface — consistent URL patterns: `` /users collection /users/{id} single resource /users/{id}/posts nested resource
5. Representations — responses are representations of the resource (JSON, XML). The resource itself lives on the server; you get a copy.
6. HATEOAS (optional in practice) — responses include links to related actions.
Idempotency:
- GET, PUT, DELETE are idempotent (same result if called multiple times)
- POST is not idempotent (creates new resource each time)
Examples
RESTful URL design
URLs are nouns identifying resources; HTTP methods are the verbs
# Blog API — RESTful URL structure
GET /articles # List all articles
POST /articles # Create a new article
GET /articles/42 # Get article 42
PUT /articles/42 # Replace article 42 completely
PATCH /articles/42 # Update some fields of article 42
DELETE /articles/42 # Delete article 42
# Nested resources
GET /articles/42/comments # Comments on article 42
POST /articles/42/comments # Add comment to article 42
DELETE /articles/42/comments/7 # Delete comment 7 on article 42Stateless auth — token on every request
No session on the server — the token carries the identity on every request
import httpx
def get_user(user_id: int, token: str) -> dict:
# Every request is self-contained — server doesn't remember previous requests
response = httpx.get(
f"https://api.example.com/users/{user_id}",
headers={"Authorization": f"Bearer {token}"}
)
response.raise_for_status()
return response.json()How well did you understand this?
Next in Web & HTTP
JSON APIs