API Design Validation
Validates REST API design patterns for consistency and RESTful compliance.
When to Use This Skill
- Designing new API endpoints
- Reviewing API changes in PRs
- Auditing existing API for consistency
- Documenting API contracts
- Debugging API behavior
Endpoint Naming Conventions
URL Structure
/api/v1/<resource>/<id>/<sub-resource>
Rules
| Rule |
Good |
Bad |
| Use nouns, not verbs |
/users |
/getUsers |
| Use plural nouns |
/users |
/user |
| Use kebab-case |
/user-profiles |
/userProfiles |
| Use lowercase |
/users |
/Users |
| No trailing slash |
/users |
/users/ |
Examples
GET /api/v1/users # List users
POST /api/v1/users # Create user
GET /api/v1/users/:id # Get user
PUT /api/v1/users/:id # Update user
DELETE /api/v1/users/:id # Delete user
GET /api/v1/users/:id/posts # List user's posts
HTTP Methods
| Method |
Purpose |
Idempotent |
Request Body |
GET |
Read resource |
Yes |
No |
POST |
Create resource |
No |
Yes |
PUT |
Replace resource |
Yes |
Yes |
PATCH |
Partial update |
Yes |
Yes |
DELETE |
Remove resource |
Yes |
No |
Method Selection
# Create new resource
POST /api/v1/users
# Full replacement (all fields required)
PUT /api/v1/users/:id
# Partial update (only changed fields)
PATCH /api/v1/users/:id
# Actions on resources (use POST)
POST /api/v1/users/:id/activate
POST /api/v1/users/:id/reset-password
Status Codes
Success (2xx)
| Code |
When to Use |
200 OK |
Successful GET, PUT, PATCH, DELETE |
201 Created |
Successful POST (resource created) |
204 No Content |
Successful DELETE (no body) |
Client Errors (4xx)
| Code |
When to Use |
400 Bad Request |
Invalid request body/params |
401 Unauthorized |
Missing/invalid authentication |
403 Forbidden |
Authenticated but not authorized |
404 Not Found |
Resource doesn't exist |
409 Conflict |
Resource conflict (duplicate) |
422 Unprocessable Entity |
Validation failed |
429 Too Many Requests |
Rate limit exceeded |
Server Errors (5xx)
| Code |
When to Use |
500 Internal Server Error |
Unexpected server error |
502 Bad Gateway |
Upstream service error |
503 Service Unavailable |
Server overloaded/maintenance |
Request/Response Schemas
Request Body
{
"data": {
"type": "user",
"attributes": {
"email": "user@example.com",
"name": "John Doe"
}
}
}
Success Response
{
"data": {
"id": "123",
"type": "user",
"attributes": {
"email": "user@example.com",
"name": "John Doe",
"created_at": "2026-01-29T04:00:00Z"
}
},
"meta": {
"request_id": "abc-123"
}
}
List Response
{
"data": [
{ "id": "1", "type": "user", "attributes": {...} },
{ "id": "2", "type": "user", "attributes": {...} }
],
"meta": {
"total": 100,
"page": 1,
"per_page": 20
},
"links": {
"self": "/api/v1/users?page=1",
"next": "/api/v1/users?page=2",
"last": "/api/v1/users?page=5"
}
}
Error Response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
},
"meta": {
"request_id": "abc-123"
}
}
Validation Checklist
Endpoint Design
HTTP Methods
Status Codes
Response Format
Common Anti-Patterns
Verbs in URLs
# ❌ Bad
GET /api/v1/getUsers
POST /api/v1/createUser
POST /api/v1/deleteUser/:id
# ✅ Good
GET /api/v1/users
POST /api/v1/users
DELETE /api/v1/users/:id
Inconsistent Naming
# ❌ Bad (mixed styles)
GET /api/v1/users
GET /api/v1/UserProfiles
GET /api/v1/user_settings
# ✅ Good (consistent kebab-case)
GET /api/v1/users
GET /api/v1/user-profiles
GET /api/v1/user-settings
Wrong Status Codes
# ❌ Bad
200 OK with error in body
404 for validation errors
500 for auth failures
# ✅ Good
400/422 for validation errors
401 for auth failures
500 only for server errors
Validation Commands
# Check route definitions
grep -r "router\." server/routes/ | grep -E "(get|post|put|patch|delete)"
# Find inconsistent naming
grep -rE "/api/v1/[A-Z]" server/ # Should find nothing
# Check for verbs in URLs
grep -rE "/(get|create|update|delete)[A-Z]" server/ # Should find nothing
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
tomevault-io