The Library Analogy
At a library:
- Resources: Books on shelves
- Actions: Borrow, return, search
- Catalog system: Organized by category, ID
You use the catalog system to find and interact with books.
REST API organizes data as resources with standard actions for creating, reading, updating, and deleting.
What Is REST?
REST = REpresentational State Transfer
An architectural style for APIs:
- Everything is a resource
- Resources have URLs
- Standard methods (GET, POST, PUT, DELETE)
- Stateless (each request is independent)
Core Concepts
Resources
Nouns, not verbs.
âś“ /users
âś“ /products
âś“ /orders
âś— /getUsers
âś— /createProduct
âś— /updateOrder
Resources are things. Methods are actions.
URLs (Endpoints)
Resource location:
/users → Collection of users
/users/123 → Specific user
/users/123/orders → User's orders
/orders/456 → Specific order
HTTP Methods (Verbs)
| Method | Action | Example |
|---|---|---|
| GET | Read | Get user data |
| POST | Create | Create new user |
| PUT | Replace | Replace entire user |
| PATCH | Update | Update user email |
| DELETE | Delete | Delete user |
CRUD Operations
CRUD = Create, Read, Update, Delete
Create: POST /users → Create user
Read: GET /users/123 → Get user
Update: PUT /users/123 → Replace user
PATCH /users/123 → Partial update
Delete: DELETE /users/123 → Delete user
Most apps are CRUD operations on resources.
Request/Response
Request Structure
POST /users
Host: api.example.com
Content-Type: application/json
Authorization: <credentials>
{
"name": "Alice",
"email": "alice@example.com"
}
Response Structure
HTTP/1.1 201 Created
Content-Type: application/json
{
"id": 123,
"name": "Alice",
"email": "alice@example.com",
"createdAt": "2025-01-01T00:00:00Z"
}
Status Codes
Success
| Code | Meaning |
|---|---|
| 200 | OK (general success) |
| 201 | Created (resource created) |
| 204 | No Content (success, no body) |
Client Errors
| Code | Meaning |
|---|---|
| 400 | Bad Request (invalid input) |
| 401 | Unauthorized (need auth) |
| 403 | Forbidden (no permission) |
| 404 | Not Found (doesn't exist) |
| 409 | Conflict (duplicate, etc.) |
| 422 | Unprocessable Entity (validation failed) |
Server Errors
| Code | Meaning |
|---|---|
| 500 | Internal Server Error |
| 502 | Bad Gateway |
| 503 | Service Unavailable |
REST Principles
1. Stateless
Each request contains all information needed.
Server doesn't remember previous requests.
No: "Continue from where we left off"
Yes: "Here's the token, here's what I need"
Scalable. Any server can handle any request.
2. Client-Server
Client and server are separate.
Client handles UI.
Server handles data.
Change one without affecting other.
3. Cacheable
Responses can be cached.
GET requests are cacheable.
Cache-Control: max-age=3600
Reduces server load.
4. Uniform Interface
Consistent patterns:
- Resource identification (URLs)
- Standard methods (HTTP verbs)
- Self-descriptive messages (JSON + status codes)
URL Design Best Practices
Use Nouns
âś“ /articles
âś“ /users/123/posts
âś— /getArticles
âś— /createNewArticle
Use Plural Names
âś“ /users
âś“ /products
âś— /user
âś— /product
Use Nested Resources Sparingly
âś“ /users/123/orders (user's orders)
âś— /users/123/orders/456/items/789/details
(too deep, use /items/789 instead)
Use Query Parameters for Filtering
GET /products?category=electronics&minPrice=100
Not: /products/electronics/minPrice/100
Pagination
Too many results? Paginate.
GET /users?page=2&limit=20
Response:
{
"data": [...],
"pagination": {
"page": 2,
"limit": 20,
"total": 150,
"pages": 8
}
}
Versioning
API changes over time.
Don't break existing clients.
URL versioning:
/v1/users
/v2/users
Header versioning:
Accept: application/vnd.api.v2+json
URL versioning is most common.
Error Responses
Consistent error format:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Email is required",
"details": [
{ "field": "email", "issue": "required" }
]
}
}
Helpful for debugging!
Common Mistakes
1. Using Verbs in URLs
âś— /getUser
âś— /createOrder
âś“ GET /users/123
âś“ POST /orders
HTTP method IS the verb.
2. Ignoring Status Codes
âś— Return 200 for everything, error in body
âś“ 404 for not found
âś“ 400 for bad request
âś“ 500 for server error
Status codes have meaning!
3. Not Versioning
Breaking change → Clients break.
Version early, before you have many clients.
4. Inconsistent Naming
/Users vs /products vs /order-items
Pick one style, stick with it.
FAQ
Q: REST vs RESTful?
REST is the style. RESTful describes an API that follows REST principles.
Q: PUT vs PATCH?
PUT replaces entire resource. PATCH updates part of it.
Q: Do I need all HTTP methods?
No! Start with GET and POST. Add others as needed.
Q: Is REST better than GraphQL?
Different tools. REST is simpler, GraphQL more flexible. Choose based on needs.
Summary
REST API organizes web services around resources, using HTTP methods for standard operations.
Key Takeaways:
- Resources are nouns (users, products)
- HTTP methods are verbs (GET, POST, PUT, DELETE)
- Stateless - each request is independent
- Status codes communicate outcomes
- Use consistent URL patterns
- Version your API
REST is the most common way to build web APIs!
Leave a Comment
Comments (0)
Be the first to comment on this concept.
Comments are approved automatically.