Anatomy of a well-designed request
1 / 8
HTTP method
GET reads without side effects, so the response can be cached and the call safely retried.
HTTP/1.1 200 OK{ "data": [ { "id": 7731, "total": 1250.0, "status": "open" }, { "id": 7702, "total": 980.5, "status": "open" } ], "hasMore": true, "nextCursor": "def456"}
Illustrative example
RESTful resource design
URI design best practices
- Use nouns, not verbs:
/customersnot/getCustomers - Hierarchical relationships:
/customers/123/orders - Plural resource names:
/productsnot/product - Use hyphens for readability:
/customer-ordersnot/customer_orders - Lowercase URIs:
/customersnot/Customers
HTTP methods & semantics
| Method | Purpose | Idempotent | Example |
|---|---|---|---|
| GET | Retrieve resource(s) | Yes | GET /customers/123 |
| POST | Create new resource | No | POST /customers |
| PUT | Replace entire resource | Yes | PUT /customers/123 |
| PATCH | Partial update | No | PATCH /customers/123 |
| DELETE | Remove resource | Yes | DELETE /customers/123 |
Response design
HTTP status codes
- 200 OK:Successful GET, PUT, PATCH, or DELETE
- 201 Created:Successful POST with location header to new resource
- 204 No Content:Successful request with no response body
- 400 Bad Request:Invalid request syntax or validation errors
- 401 Unauthorized:Authentication required
- 403 Forbidden:Authenticated but not authorized
- 404 Not Found:Resource does not exist
- 409 Conflict:Resource state conflict (e.g., duplicate)
- 429 Too Many Requests:Rate limit exceeded
- 500 Internal Server Error:Unhandled server error
Error response format
Consistent error responses improve developer experience:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email format",
"target": "email",
"details": [
{
"field": "email",
"message": "Must be a valid email address"
}
]
}
}Pagination, filtering & sorting
Pagination strategies
- Offset-based:
?skip=20&limit=10- Simple but inefficient for large datasets - Cursor-based:
?cursor=abc123&limit=10- Efficient for real-time data - Page-based:
?page=3&pageSize=10- User-friendly for UI pagination
Include pagination metadata in response: totalCount, hasMore, nextCursor
Filtering & sorting
- Simple filters:
?status=active&category=electronics - Comparison operators:
?price[gte]=100&price[lte]=500 - Full-text search:
?q=laptop&searchFields=name,description - Sorting:
?sortBy=createdAt&order=desc - Field selection:
?fields=id,name,email