api-rest-design

---

name: api-rest-design description: Apply when designing RESTful APIs, defining endpoints, HTTP methods, status codes, and response formats. version: 1.1.0 tokens: ~700 confidence: high sources:

• https://restfulapi.net/
• https://www.rfc-editor.org/rfc/rfc9110 last_validated: 2025-12-10 next_review: 2025-12-24 tags: [api, rest, backend, design]

---

When to Use

Apply when designing RESTful APIs, defining endpoints, HTTP methods, status codes, and response formats.

Patterns

Pattern 1: Resource Naming

# Source: https://restfulapi.net/resource-naming/
GOOD:
GET    /users              # List users
GET    /users/123          # Get user 123
POST   /users              # Create user
PUT    /users/123          # Update user 123
DELETE /users/123          # Delete user 123
GET    /users/123/orders   # User's orders (nested resource)

BAD:
GET    /getUsers           # Verb in URL
POST   /createUser         # Verb in URL
GET    /user/123           # Singular (use plural)

Pattern 2: HTTP Status Codes

# Source: https://www.rfc-editor.org/rfc/rfc9110
Success:
200 OK           - GET/PUT success with body
201 Created      - POST success, include Location header
204 No Content   - DELETE success, no body

Client Errors:
400 Bad Request  - Invalid input/payload
401 Unauthorized - Missing/invalid auth
403 Forbidden    - Auth valid, no permission
404 Not Found    - Resource doesn't exist
409 Conflict     - Resource state conflict
422 Unprocessable - Validation failed

Server Errors:
500 Internal     - Unexpected server error
503 Unavailable  - Service temporarily down

Pattern 3: Response Format

// Source: https://restfulapi.net/
// Success response
{
  "data": { "id": 123, "name": "John" },
  "meta": { "timestamp": "2025-12-10T12:00:00Z" }
}

// Error response
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [{ "field": "email", "message": "Must be valid email" }]
  }
}

// List with pagination
{
  "data": [...],
  "meta": { "total": 100, "page": 1, "limit": 20 }
}

Pattern 4: Filtering & Pagination

# Source: https://restfulapi.net/
GET /users?status=active&role=admin     # Filter
GET /users?sort=created_at:desc         # Sort
GET /users?page=2&limit=20              # Pagination
GET /users?fields=id,name,email         # Field selection

Pattern 5: Versioning

# Source: https://restfulapi.net/versioning/
URL path (recommended):
GET /api/v1/users

Header (alternative):
Accept: application/vnd.api+json;version=1

Anti-Patterns

• Verbs in URLs - Use nouns: /users not /getUsers
• Wrong status codes - Don't return 200 for errors
• Inconsistent responses - Same format for all endpoints
• Missing pagination - Always paginate lists
• No versioning - Plan for API evolution

Verification Checklist

• Resource URLs use plural nouns
• Correct HTTP methods (GET read, POST create, etc.)
• Appropriate status codes returned
• Consistent error response format
• Pagination on list endpoints
• API versioning strategy defined