RESTful Architecture

REST: The Backbone of Web APIs

REST (Representational State Transfer) is an architectural style, not a protocol. It defines constraints that make APIs scalable, simple, and predictable.

The 6 REST Constraints

1. Client-Server: Frontend and backend are separate, evolving independently.
2. Stateless: Each request contains ALL information needed. The server stores no session state between requests.
3. Cacheable: Responses must declare if they're cacheable to improve performance.
4. Uniform Interface: Resources are identified by URIs. Representations (JSON/XML) are used to manipulate them.
5. Layered System: Client can't tell if it's connected to the end server or a load balancer/CDN.
6. Code on Demand (Optional): Servers can send executable code (JavaScript) to clients.

HTTP Methods & Their Semantics

Method	CRUD	Idempotent?	Safe?	Example
GET	Read	Yes	Yes	GET /api/users/123
POST	Create	No	No	POST /api/users
PUT	Replace	Yes	No	PUT /api/users/123
PATCH	Partial Update	No*	No	PATCH /api/users/123
DELETE	Delete	Yes	No	DELETE /api/users/123

Status Codes You Must Know

• 200 OK — Success
• 201 Created — Resource created (POST)
• 204 No Content — Success with no body (DELETE)
• 301 Moved Permanently — URL changed (SEO impact!)
• 400 Bad Request — Client sent invalid data
• 401 Unauthorized — Not authenticated
• 403 Forbidden — Authenticated but not authorized
• 404 Not Found
• 429 Too Many Requests — Rate limited
• 500 Internal Server Error
• 503 Service Unavailable

Resource Naming Best Practices

• Use nouns, not verbs: /api/users not /api/getUsers
• Use plural: /api/users not /api/user
• Use nesting for relationships: /api/users/123/orders
• Use query params for filtering: /api/users?role=admin&sort=name

Idempotency Explained

An operation is idempotent if calling it multiple times produces the same result. GET, PUT, and DELETE are idempotent. POST is not — calling POST /users twice creates two users.

This matters for retry logic: if a network error occurs during a PUT request, you can safely retry. If it happens during POST, you might create duplicates.