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-10T00:00:00.000Z
next_review	2025-12-24T00:00:00.000Z
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": , :  }
}