Files
skills/public/api-rest-api-design.md

22 KiB

name, description
name description
api-rest-api-design Designing RESTful APIs from scratch

REST API Design

Scope: RESTful resource modeling, HTTP semantics, URL conventions, status codes Lines: ~280 Last Updated: 2025-10-18

When to Use This Skill

Activate this skill when:

  • Designing RESTful APIs from scratch
  • Modeling resources and relationships
  • Choosing appropriate HTTP methods
  • Structuring API endpoints and URLs
  • Selecting correct HTTP status codes
  • Implementing API versioning strategies
  • Handling errors and validation
  • Optimizing for idempotency and caching

Core Concepts

RESTful Principles

REST (Representational State Transfer): Architectural style for distributed systems.

Key principles:

  • Stateless: Each request contains all needed information
  • Resource-based: URLs identify resources (nouns, not verbs)
  • HTTP methods: Use standard methods (GET, POST, PUT, DELETE)
  • Uniform interface: Consistent patterns across API
  • Self-descriptive: Responses include metadata (Content-Type, status codes)

Resource Modeling

Resources are Nouns, Not Verbs

❌ Wrong (verb-based):

POST /createUser
POST /getUserById
POST /updateUserEmail
POST /deleteUser

✅ Correct (resource-based):

POST   /users          # Create user
GET    /users/:id      # Get user
PUT    /users/:id      # Update user
DELETE /users/:id      # Delete user

Resource Naming Conventions

Use plural nouns:

GET /users          # ✅ Consistent plural
GET /user           # ❌ Singular (inconsistent)

Lowercase with hyphens (not underscores or camelCase):

GET /user-profiles       # ✅ Kebab-case
GET /user_profiles       # ❌ Snake_case (harder to read in URLs)
GET /userProfiles        # ❌ camelCase (inconsistent)

Hierarchy for relationships:

GET /users/:id/posts              # User's posts
GET /users/:id/posts/:postId      # Specific post by user
GET /posts/:id/comments           # Comments on post

Collections vs Singular Resources:

GET /users           # Collection (returns array)
GET /users/42        # Singular resource (returns object)
GET /users/me        # Special singular (current user)

HTTP Method Semantics

GET - Retrieve Resources

Purpose: Fetch data without side effects

Characteristics:

  • Safe: Doesn't modify state
  • Idempotent: Multiple identical requests = same result
  • Cacheable: Can be cached by intermediaries

Examples:

GET /users                    # List all users
GET /users?page=2&limit=20    # Paginated list
GET /users/42                 # Get user by ID
GET /users/42/posts           # Get user's posts
GET /posts?author=alice       # Filtered list

Response:

// Single resource
{
  "id": 42,
  "email": "[email protected]",
  "name": "Alice"
}

// Collection
{
  "data": [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
  ],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20
  }
}

POST - Create Resources

Purpose: Create new resource or trigger action

Characteristics:

  • Not safe: Modifies state
  • Not idempotent: Multiple requests create multiple resources
  • Not cacheable

Examples:

POST /users              # Create new user
POST /posts              # Create new post
POST /posts/42/publish   # Action (publish post)

Request:

POST /users
Content-Type: application/json

{
  "email": "[email protected]",
  "name": "Alice",
  "password": "secret123"
}

Response (201 Created):

HTTP/1.1 201 Created
Location: /users/42
Content-Type: application/json

{
  "id": 42,
  "email": "[email protected]",
  "name": "Alice",
  "created_at": "2025-10-18T12:00:00Z"
}

Use POST for non-idempotent actions:

POST /orders/42/payments    # Process payment (not idempotent)
POST /users/42/send-email   # Send email (side effect)

PUT - Replace Resource

Purpose: Replace entire resource (or create if doesn't exist)

Characteristics:

  • Not safe: Modifies state
  • Idempotent: Multiple identical requests = same result
  • Not cacheable

Examples:

PUT /users/42            # Replace entire user
PUT /posts/123           # Replace entire post

Request (must include all fields):

PUT /users/42
Content-Type: application/json

{
  "email": "[email protected]",
  "name": "Alice Cooper",  // Updated
  "bio": "Developer"       // All fields required
}

Response (200 OK):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "email": "[email protected]",
  "name": "Alice Cooper",
  "bio": "Developer",
  "updated_at": "2025-10-18T12:00:00Z"
}

PUT for upsert (create if not exists):

PUT /users/[email protected]   # Create or replace by email

PATCH - Partial Update

Purpose: Partially update resource (modify specific fields)

Characteristics:

  • Not safe: Modifies state
  • Not idempotent (depends on implementation)
  • Not cacheable

Examples:

PATCH /users/42          # Update specific fields
PATCH /posts/123         # Update subset of post

Request (only modified fields):

PATCH /users/42
Content-Type: application/json

{
  "name": "Alice Cooper"   // Only update name
}

Response (200 OK):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "email": "[email protected]",
  "name": "Alice Cooper",      // Updated
  "bio": "Developer",          // Unchanged
  "updated_at": "2025-10-18T12:00:00Z"
}

PUT vs PATCH:

PUT /users/42       # Replace entire user (all fields required)
PATCH /users/42     # Update specific fields (partial update)

DELETE - Remove Resource

Purpose: Delete resource

Characteristics:

  • Not safe: Modifies state
  • Idempotent: Deleting twice = same result (404 second time)
  • Not cacheable

Examples:

DELETE /users/42         # Delete user
DELETE /posts/123        # Delete post

Response (204 No Content):

HTTP/1.1 204 No Content

Or (200 OK with body):

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "User deleted successfully",
  "id": 42
}

Soft delete (use PATCH instead):

PATCH /users/42
{"deleted_at": "2025-10-18T12:00:00Z"}

HTTP Status Codes

Success Codes (2xx)

200 OK: Standard success response (GET, PUT, PATCH)

GET /users/42           → 200 OK + user object
PUT /users/42           → 200 OK + updated user
PATCH /users/42         → 200 OK + updated user

201 Created: Resource created successfully (POST)

POST /users             → 201 Created + new user
Location: /users/42

204 No Content: Success with no response body (DELETE)

DELETE /users/42        → 204 No Content

206 Partial Content: Partial resource (range requests)

GET /videos/123
Range: bytes=0-1024     → 206 Partial Content

Redirection Codes (3xx)

301 Moved Permanently: Resource permanently moved

GET /old-endpoint       → 301 Moved Permanently
Location: /new-endpoint

304 Not Modified: Cached version is still valid

GET /users/42
If-None-Match: "abc123" → 304 Not Modified

Client Error Codes (4xx)

400 Bad Request: Invalid request (validation failed)

POST /users
{"email": "invalid"}    → 400 Bad Request
{
  "error": "Validation failed",
  "details": {
    "email": ["Must be valid email address"]
  }
}

401 Unauthorized: Authentication required or failed

GET /users/me           → 401 Unauthorized
{
  "error": "Authentication required",
  "message": "Missing or invalid token"
}

403 Forbidden: Authenticated but not authorized

DELETE /users/99        → 403 Forbidden
{
  "error": "Forbidden",
  "message": "You don't have permission to delete this user"
}

404 Not Found: Resource doesn't exist

GET /users/99999        → 404 Not Found
{
  "error": "Not found",
  "message": "User not found"
}

409 Conflict: Request conflicts with current state

POST /users
{"email": "[email protected]"}  → 409 Conflict
{
  "error": "Conflict",
  "message": "User with this email already exists"
}

422 Unprocessable Entity: Valid syntax, but semantic errors

POST /orders
{"product_id": 999}     → 422 Unprocessable Entity
{
  "error": "Unprocessable entity",
  "message": "Product not found"
}

429 Too Many Requests: Rate limit exceeded

GET /users              → 429 Too Many Requests
Retry-After: 60
{
  "error": "Rate limit exceeded",
  "message": "Try again in 60 seconds"
}

Server Error Codes (5xx)

500 Internal Server Error: Unexpected server error

GET /users              → 500 Internal Server Error
{
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}

502 Bad Gateway: Upstream server error (proxy/gateway)

GET /users              → 502 Bad Gateway
{
  "error": "Bad gateway",
  "message": "Upstream service unavailable"
}

503 Service Unavailable: Server temporarily unavailable

GET /users              → 503 Service Unavailable
Retry-After: 120
{
  "error": "Service unavailable",
  "message": "Server is under maintenance"
}

URL Structure Best Practices

Hierarchical Resource Relationships

GET /users/:userId/posts                    # User's posts
GET /users/:userId/posts/:postId            # Specific post
GET /users/:userId/posts/:postId/comments   # Post's comments

Limit nesting to 2-3 levels:

✅ GET /posts/:postId/comments/:commentId
❌ GET /users/:userId/posts/:postId/comments/:commentId/replies/:replyId

Query Parameters for Filtering

Filtering:

GET /posts?status=published&author=alice
GET /users?role=admin&verified=true

Sorting:

GET /posts?sort=created_at:desc
GET /users?sort=-created_at              # Descending (- prefix)
GET /products?sort=price:asc,name:asc    # Multi-field

Pagination:

GET /posts?page=2&limit=20               # Page-based
GET /posts?offset=20&limit=20            # Offset-based
GET /posts?cursor=abc123&limit=20        # Cursor-based (best for large datasets)

Field selection (sparse fieldsets):

GET /users?fields=id,email,name          # Only return specified fields
GET /posts?include=author,comments       # Include related resources

Action Endpoints (Non-CRUD)

Use verbs for actions (not CRUD):

POST /posts/:id/publish       # Publish post
POST /users/:id/send-reset    # Send password reset
POST /orders/:id/cancel       # Cancel order
POST /carts/:id/checkout      # Checkout cart

Alternative: Use status changes:

PATCH /posts/:id              # { "status": "published" }
PATCH /orders/:id             # { "status": "cancelled" }

Idempotency

Idempotent Methods

Safe + Idempotent: GET, HEAD, OPTIONS Idempotent (not safe): PUT, DELETE

GET: Multiple requests return same data

GET /users/42       # Always returns same user (if unchanged)

PUT: Multiple identical requests = same result

PUT /users/42
{"name": "Alice"}   # Setting name to "Alice" multiple times = same result

DELETE: Multiple deletes = same result

DELETE /users/42    # First: 204 No Content
DELETE /users/42    # Second: 404 Not Found (idempotent result)

Non-Idempotent Methods

POST: Multiple requests create multiple resources

POST /orders        # Creates new order each time
POST /payments      # Processes payment each time (dangerous!)

Making POST idempotent (idempotency keys):

POST /payments
Idempotency-Key: abc123
{"amount": 100}

# Second request with same key returns original response (no duplicate charge)
POST /payments
Idempotency-Key: abc123
{"amount": 100}     # Returns 200 OK with original payment (no new charge)

Implementation:

def create_payment(request):
    idempotency_key = request.headers.get('Idempotency-Key')

    # Check if already processed
    existing = db.query("SELECT * FROM payments WHERE idempotency_key = %s", [idempotency_key])
    if existing:
        return 200, existing  # Return original result

    # Process new payment
    payment = process_payment(request.body)
    payment.idempotency_key = idempotency_key
    db.save(payment)

    return 201, payment

REST Maturity Model (Richardson)

Level 0: The Swamp of POX (Plain Old XML)

Single endpoint, single method:

POST /api
{"method": "getUser", "id": 42}
{"method": "createUser", "data": {...}}

❌ Not RESTful

Level 1: Resources

Multiple endpoints (resources):

GET /users/42
POST /users

✅ Resource-based, but not using HTTP methods correctly

Level 2: HTTP Verbs

Proper use of HTTP methods:

GET    /users/42      # Retrieve
POST   /users         # Create
PUT    /users/42      # Update
DELETE /users/42      # Delete

✅ RESTful, uses HTTP semantics

Level 3: Hypermedia (HATEOAS)

Hypermedia As The Engine Of Application State:

Responses include links to related resources:

GET /users/42

{
  "id": 42,
  "name": "Alice",
  "email": "[email protected]",
  "_links": {
    "self": {"href": "/users/42"},
    "posts": {"href": "/users/42/posts"},
    "followers": {"href": "/users/42/followers"},
    "edit": {"href": "/users/42", "method": "PUT"},
    "delete": {"href": "/users/42", "method": "DELETE"}
  }
}

Benefits:

  • Self-documenting API
  • Clients discover actions dynamically
  • Server can change URLs without breaking clients

Trade-offs:

  • Increased response size
  • More complex client implementation
  • Rarely fully implemented in practice

Content Negotiation

Request Content Type

Client specifies format:

POST /users
Content-Type: application/json

{"name": "Alice"}

Server validates:

415 Unsupported Media Type (if Content-Type not supported)

Response Content Type

Client requests format:

GET /users/42
Accept: application/json         # Request JSON

Server responds:

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 42, "name": "Alice"}

Multiple formats supported:

GET /users/42
Accept: application/xml          # Request XML

HTTP/1.1 200 OK
Content-Type: application/xml

<user><id>42</id><name>Alice</name></user>

Versioning via content type:

Accept: application/vnd.myapi.v2+json

API Versioning Strategies

URL Versioning (Most Common)

GET /v1/users/42
GET /v2/users/42

Pros: Simple, explicit, easy to route Cons: URL pollution, hard to migrate

Header Versioning

GET /users/42
Accept: application/vnd.myapi.v2+json

Pros: Clean URLs, RESTful Cons: Harder to test (can't use browser directly)

Query Parameter Versioning

GET /users/42?version=2

Pros: Simple, easy to test Cons: Less RESTful, query params should be for filtering

Recommendation: URL versioning (/v1/, /v2/) for simplicity


HTTP Status Code Quick Reference

Code Name Use Case
200 OK Successful GET, PUT, PATCH
201 Created Successful POST (resource created)
204 No Content Successful DELETE or PUT with no response
400 Bad Request Validation error, malformed request
401 Unauthorized Authentication required or failed
403 Forbidden Authenticated but not authorized
404 Not Found Resource doesn't exist
409 Conflict Resource already exists, version conflict
422 Unprocessable Entity Valid syntax, semantic error
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Unexpected server error
502 Bad Gateway Upstream service error
503 Service Unavailable Server under maintenance

REST API Checklist

Resource Modeling:
[ ] Resources are nouns (not verbs)
[ ] Plural nouns for collections (/users, /posts)
[ ] Kebab-case for multi-word resources (/user-profiles)
[ ] Hierarchical relationships (/users/:id/posts)

HTTP Methods:
[ ] GET for retrieval (safe, idempotent)
[ ] POST for creation (non-idempotent)
[ ] PUT for full replacement (idempotent)
[ ] PATCH for partial updates
[ ] DELETE for removal (idempotent)

Status Codes:
[ ] 200 for successful GET/PUT/PATCH
[ ] 201 for successful POST (with Location header)
[ ] 204 for successful DELETE
[ ] 400 for validation errors
[ ] 401 for authentication errors
[ ] 403 for authorization errors
[ ] 404 for not found
[ ] 500 for server errors

Idempotency:
[ ] GET, PUT, DELETE are idempotent
[ ] POST uses idempotency keys for critical operations
[ ] PATCH operations are designed to be repeatable

Response Format:
[ ] Consistent error structure
[ ] Pagination metadata for collections
[ ] Timestamps in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)
[ ] Snake_case or camelCase (consistent across API)

Security:
[ ] Authentication required for sensitive endpoints
[ ] Authorization checks before operations
[ ] Rate limiting implemented
[ ] Input validation on all endpoints

Common REST Anti-Patterns

❌ Verbs in URLs: /getUser, /createPost ✅ Use nouns + HTTP methods: GET /users, POST /posts

❌ Using GET for actions: GET /users/42/delete ✅ Use DELETE: DELETE /users/42

❌ Returning 200 for errors: 200 OK {"error": "User not found"} ✅ Use proper status codes: 404 Not Found {"error": "User not found"}

❌ Inconsistent naming: /users, /post, /getComments ✅ Consistent plural nouns: /users, /posts, /comments

❌ Deep nesting: /orgs/:id/teams/:id/users/:id/posts/:id/comments/:id ✅ Limit to 2-3 levels: /posts/:id/comments or /comments?post_id=:id

❌ Ignoring idempotency: POST /payments (no idempotency key) ✅ Implement idempotency: Idempotency-Key header

❌ Exposing internal IDs: /users/42 (auto-increment) ✅ Use UUIDs or obfuscated IDs: /users/550e8400-e29b-41d4-a716-446655440000


  • http-caching-strategies.md - Cache headers, ETags, conditional requests
  • api-authentication.md - JWT, OAuth2, API keys
  • api-rate-limiting.md - Rate limiting strategies
  • graphql-vs-rest.md - When to use GraphQL vs REST
  • openapi-documentation.md - Documenting APIs with OpenAPI/Swagger

Level 3: Resources

This skill includes comprehensive Level 3 resources in the /resources/ directory:

Reference Material (resources/REFERENCE.md)

Comprehensive 1,800+ line reference covering:

  • REST principles (stateless, resource-based, uniform interface)
  • HTTP methods (GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD)
  • Status codes (proper usage for 2xx, 3xx, 4xx, 5xx)
  • URL design and resource naming
  • Request/response formats (JSON, content negotiation)
  • Pagination strategies (offset, cursor, page-based)
  • Filtering, sorting, and searching
  • Versioning strategies (URI, header, content negotiation)
  • Error handling and problem details (RFC 7807)
  • HATEOAS and hypermedia
  • Rate limiting and throttling
  • Caching (ETags, Cache-Control, conditional requests)
  • Authentication and authorization
  • CORS
  • API documentation (OpenAPI/Swagger)
  • Security best practices
  • Performance optimization
  • Testing strategies
  • Common patterns and anti-patterns

Executable Scripts (resources/scripts/)

validate_api.py:

  • Validate REST API design against best practices
  • Check resource naming conventions, HTTP method usage, status codes
  • Validate response format consistency, security headers, rate limiting
  • Support for OpenAPI specs and custom formats
  • JSON output for CI/CD integration

generate_openapi.py:

  • Generate OpenAPI specs from Python (FastAPI, Flask) or JavaScript (Express) code
  • Convert Swagger 2.0 to OpenAPI 3.0
  • Generate client code (Python, JavaScript, TypeScript) from OpenAPI specs
  • Automatic endpoint detection and schema generation

test_api.sh:

  • Test REST API endpoints with various scenarios
  • CRUD operations, error handling, authentication
  • Pagination, filtering, sorting, caching
  • Rate limiting, CORS, content negotiation
  • Save responses and generate JSON reports

Complete Examples (resources/examples/)

python/fastapi_rest.py:

  • Complete REST API with FastAPI
  • Resource-based endpoints, proper HTTP methods and status codes
  • Pagination, filtering, sorting
  • Authentication with Bearer tokens
  • Rate limiting, caching headers
  • Error handling with RFC 7807 format
  • Request validation with Pydantic

node/express_rest.js:

  • Complete REST API with Express.js
  • Middleware for authentication, rate limiting, validation
  • Error handling and logging
  • Security headers with Helmet
  • Request ID tracking

openapi/petstore.yaml:

  • Complete OpenAPI 3.0 specification
  • User management API example
  • Components, schemas, responses
  • Security schemes (Bearer auth)
  • Pagination, filtering, error responses

typescript/api_client.ts:

  • Type-safe API client
  • Request/response interceptors
  • Retry logic and error handling
  • Caching with ETags
  • TypeScript interfaces for all models

curl/test_requests.sh:

  • Comprehensive curl examples
  • CRUD operations, filtering, sorting, pagination
  • Error handling, authentication, conditional requests
  • CORS preflight, rate limiting, compression
  • Bulk operations and async patterns

Usage

# Validate API design
./resources/scripts/validate_api.py openapi.json --type spec --json

# Generate OpenAPI from code
./resources/scripts/generate_openapi.py from-code api.py --framework fastapi -o openapi.json

# Test API endpoints
./resources/scripts/test_api.sh --url https://api.example.com --api-key TOKEN --verbose

# Run curl examples
cd resources/examples/curl && ./test_requests.sh

# Run FastAPI example
cd resources/examples/python && python fastapi_rest.py

# Run Express example
cd resources/examples/node && node express_rest.js

Last Updated: 2025-10-27 Format Version: 1.0 (Atomic)