Fundamental Principles of REST API
REST (Representational State Transfer) is an architectural style for designing web services. It is based on six constraints.
| Constraint | Description |
|---|
| 1. Client-Server | Separation of Concerns - Client (UI) ↔ Server (Data) via HTTP |
| 2. Stateless | Each request is independent. Server doesn’t hold session state |
| 3. Cacheable | Responses must indicate whether they are cacheable |
| 4. Uniform Interface | Resource identification, self-descriptive messages, HATEOAS |
| 5. Layered System | Transparent addition of intermediate layers (load balancers, proxies) |
| 6. Code on Demand | (Optional) Send code to client when needed |
Resource Design
Naming Conventions
✅ Good Examples:
| Method | Endpoint | Description |
|---|
| GET | /users | Get user list |
| GET | /users/123 | Get specific user |
| GET | /users/123/orders | Get user’s orders |
| POST | /users | Create new user |
| PUT | /users/123 | Update user |
| DELETE | /users/123 | Delete user |
❌ Bad Examples:
| Method | Endpoint | Problem |
|---|
| GET | /getUsers | Verb in URL |
| GET | /user/123 | Singular form |
| POST | /users/create | Redundant action |
| GET | /users/123/getOrders | Verb in URL |
HTTP Methods
| Method | Description |
|---|
| GET | Retrieve resource (Idempotent, Safe) |
| POST | Create new resource |
| PUT | Replace entire resource (Idempotent) |
| PATCH | Partial update of resource |
| DELETE | Delete resource (Idempotent) |
| HEAD | Get headers only (no body) |
| OPTIONS | Get supported methods |
HTTP Status Codes
Success (2xx)
| Code | Name | Description |
|---|
| 200 | OK | Request succeeded |
| 201 | Created | Resource created |
| 204 | No Content | Success with no body |
Client Error (4xx)
| Code | Name | Description |
|---|
| 400 | Bad Request | Invalid request format |
| 401 | Unauthorized | Authentication required |
| 403 | Forbidden | Access denied |
| 404 | Not Found | Resource not found |
| 422 | Unprocessable Entity | Validation error |
Server Error (5xx)
| Code | Name | Description |
|---|
| 500 | Internal Server Error | Server error |
| 503 | Service Unavailable | Temporary unavailable |
Error Handling
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request parameters",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
}
GET /users?offset=20&limit=10
Response:
{
"data": [...],
"pagination": {
"total": 100,
"offset": 20,
"limit": 10,
"has_more": true
}
}
GET /users?cursor=abc123&limit=10
Response:
{
"data": [...],
"pagination": {
"next_cursor": "def456",
"has_more": true
}
}
Versioning
| Strategy | Example | Notes |
|---|
| URL Path Versioning (Recommended) | GET /v1/users, GET /v2/users | Most common |
| Query Parameter | GET /users?version=1 | Simple |
| Header | Accept: application/vnd.api+json;version=1 | Clean URLs |
Summary
Following REST API design principles helps create:
- Consistency: Predictable API behavior
- Scalability: Easy to extend and maintain
- Developer Experience: Intuitive and easy to use
- Interoperability: Works well with various clients
← Back to list 