tomevault-io REST API Designer
Design RESTful APIs with proper resource modeling and endpoint structure.
Quick Start
Use resource-based URLs with plural nouns, proper HTTP methods, and consistent patterns.
Instructions
Core REST Principles
Resources, not actions:
Good: GET /users, POST /users
Bad: GET /getUsers, POST /createUser
Use HTTP methods correctly:
- GET: Retrieve (safe, idempotent)
- POST: Create (not idempotent)
- PUT: Replace (idempotent)
- PATCH: Partial update (not idempotent)
- DELETE: Remove (idempotent)
Use plural nouns:
Good: /products, /orders
Bad: /product, /order
Resource Modeling
Identify resources:
- List main entities (users, products, orders)
- Identify relationships (user has orders, order has items)
- Determine hierarchies (posts have comments)
Design URL structure:
/api/v1/resources
/api/v1/resources/{id}
/api/v1/resources/{id}/sub-resources
Example - Blog API:
GET /api/v1/posts # List posts
POST /api/v1/posts # Create post
GET /api/v1/posts/{id} # Get post
PUT /api/v1/posts/{id} # Replace post
PATCH /api/v1/posts/{id} # Update post
DELETE /api/v1/posts/{id} # Delete post
GET /api/v1/posts/{id}/comments # List comments
POST /api/v1/posts/{id}/comments # Create comment
HTTP Methods
GET - Retrieve resources:
GET /api/v1/users # List all users
GET /api/v1/users/{id} # Get specific user
GET /api/v1/users?role=admin # Filter users
Response:
{
"data": [
{ "id": 1, "name": "John" }
],
"meta": {
"total": 100,
"page": 1
}
}
POST - Create resources:
POST /api/v1/users
Content-Type: application/json
{
"name": "John Doe",
"email": "john@example.com"
}
Response (201 Created):
{
"id": 123,
"name": "John Doe",
"email": "john@example.com",
"created_at": "2024-01-01T00:00:00Z"
}
PUT - Replace resource:
PUT /api/v1/users/{id}
Content-Type: application/json
{
"name": "John Smith",
"email": "john.smith@example.com"
}
PATCH - Partial update:
PATCH /api/v1/users/{id}
Content-Type: application/json
{
"email": "newemail@example.com"
}
DELETE - Remove resource:
DELETE /api/v1/users/{id}
Response (204 No Content or 200 with confirmation)
Query Parameters
Filtering:
GET /api/v1/products?category=electronics&price_min=100
Sorting:
GET /api/v1/products?sort=price&order=desc
GET /api/v1/products?sort=-price # Descending
Pagination:
GET /api/v1/products?page=2&per_page=20
GET /api/v1/products?offset=20&limit=20
Field selection:
GET /api/v1/users?fields=id,name,email
Search:
GET /api/v1/products?q=laptop
Nested Resources
One level (recommended):
GET /api/v1/users/{id}/orders
POST /api/v1/users/{id}/orders
Avoid deep nesting:
Bad: /api/v1/users/{id}/orders/{id}/items/{id}/reviews
Better: /api/v1/reviews?item_id={id}
Alternative - flat with filters:
GET /api/v1/orders?user_id={id}
GET /api/v1/comments?post_id={id}
Response Format
Success response:
{
"data": {
"id": 1,
"name": "Product"
},
"meta": {
"timestamp": "2024-01-01T00:00:00Z"
}
}
List response:
{
"data": [
{ "id": 1, "name": "Item 1" },
{ "id": 2, "name": "Item 2" }
],
"meta": {
"total": 100,
"page": 1,
"per_page": 20
},
"links": {
"self": "/api/v1/items?page=1",
"next": "/api/v1/items?page=2",
"prev": null
}
}
Error response:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid input",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
}
Status Codes
Success:
- 200 OK: Successful GET, PUT, PATCH, DELETE
- 201 Created: Successful POST
- 204 No Content: Successful DELETE with no response body
Client errors:
- 400 Bad Request: Invalid input
- 401 Unauthorized: Missing/invalid auth
- 403 Forbidden: Insufficient permissions
- 404 Not Found: Resource doesn't exist
- 409 Conflict: Resource conflict
- 422 Unprocessable Entity: Validation error
Server errors:
- 500 Internal Server Error: Server error
- 503 Service Unavailable: Temporary unavailability
Versioning
URL versioning (recommended):
/api/v1/users
/api/v2/users
Header versioning:
GET /api/users
Accept: application/vnd.myapi.v1+json
Query parameter:
GET /api/users?version=1
Authentication
JWT Bearer token:
GET /api/v1/users
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
API Key:
GET /api/v1/users
X-API-Key: your-api-key-here
Basic Auth:
GET /api/v1/users
Authorization: Basic base64(username:password)
Rate Limiting
Include headers:
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
Response when exceeded (429):
{
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests",
"retry_after": 60
}
}
HATEOAS (Optional)
Include links to related resources:
{
"id": 1,
"name": "Product",
"links": {
"self": "/api/v1/products/1",
"category": "/api/v1/categories/5",
"reviews": "/api/v1/products/1/reviews"
}
}
Common Patterns
Bulk Operations
Bulk create:
POST /api/v1/users/bulk
Content-Type: application/json
{
"users": [
{ "name": "User 1" },
{ "name": "User 2" }
]
}
Bulk update:
PATCH /api/v1/users/bulk
Content-Type: application/json
{
"updates": [
{ "id": 1, "status": "active" },
{ "id": 2, "status": "inactive" }
]
}
Async Operations
Long-running operation:
POST /api/v1/reports
Response: 202 Accepted
{
"job_id": "abc123",
"status": "processing",
"status_url": "/api/v1/jobs/abc123"
}
Check status:
GET /api/v1/jobs/abc123
{
"status": "completed",
"result_url": "/api/v1/reports/xyz789"
}
File Upload
Single file:
POST /api/v1/files
Content-Type: multipart/form-data
file: [binary data]
With metadata:
POST /api/v1/documents
Content-Type: multipart/form-data
file: [binary data]
title: "Document Title"
category: "reports"
Webhooks
Register webhook:
POST /api/v1/webhooks
{
"url": "https://example.com/webhook",
"events": ["order.created", "order.updated"]
}
Health Check
GET /api/health
{
"status": "healthy",
"version": "1.0.0",
"timestamp": "2024-01-01T00:00:00Z"
}
Example API Design
E-commerce API
Products:
GET /api/v1/products
POST /api/v1/products
GET /api/v1/products/{id}
PUT /api/v1/products/{id}
DELETE /api/v1/products/{id}
GET /api/v1/products/{id}/reviews
Orders:
GET /api/v1/orders
POST /api/v1/orders
GET /api/v1/orders/{id}
PATCH /api/v1/orders/{id}
GET /api/v1/orders/{id}/items
Customers:
GET /api/v1/customers
POST /api/v1/customers
GET /api/v1/customers/{id}
GET /api/v1/customers/{id}/orders
Cart:
GET /api/v1/cart
POST /api/v1/cart/items
DELETE /api/v1/cart/items/{id}
POST /api/v1/cart/checkout
Best Practices
Use consistent naming:
- Lowercase URLs
- Hyphens for multi-word resources:
/order-items - Consistent date formats: ISO 8601
Include metadata:
- Timestamps (created_at, updated_at)
- Pagination info
- API version
Validate input:
- Check required fields
- Validate formats
- Sanitize data
Handle errors gracefully:
- Clear error messages
- Appropriate status codes
- Include error codes for client handling
Document everything:
- Use OpenAPI/Swagger
- Include examples
- Document rate limits
Troubleshooting
Unclear resource boundaries:
- Focus on nouns, not verbs
- Think about data entities
- Consider client needs
Deep nesting:
- Limit to one level
- Use query parameters for filtering
- Create separate endpoints
Inconsistent responses:
- Use response templates
- Standardize error format
- Document response structure
Converted and distributed by TomeVault — claim your Tome and manage your conversions.