REST API Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: rest-api for comprehensive documentation.

Resource Naming

# Collections (plural nouns)
GET    /users              # List users
POST   /users              # Create user
GET    /users/{id}         # Get user
PUT    /users/{id}         # Update user
DELETE /users/{id}         # Delete user

# Nested resources
GET    /users/{id}/posts   # User's posts
POST   /users/{id}/posts   # Create user's post

# Avoid verbs in URLs
❌ GET /getUsers
❌ POST /createUser
✅ GET /users
✅ POST /users

HTTP Methods

| Method | Purpose | Idempotent | |--------|---------|------------| | GET | Read resource | Yes | | POST | Create resource | No | | PUT | Replace resource | Yes | | PATCH | Partial update | Yes | | DELETE | Remove resource | Yes |

Status Codes

| Code | Meaning | Use Case | |------|---------|----------| | 200 | OK | Successful GET/PUT/PATCH | | 201 | Created | Successful POST | | 204 | No Content | Successful DELETE | | 400 | Bad Request | Validation error | | 401 | Unauthorized | Missing/invalid auth | | 403 | Forbidden | No permission | | 404 | Not Found | Resource doesn't exist | | 409 | Conflict | Duplicate/conflict | | 422 | Unprocessable | Semantic error | | 500 | Server Error | Internal error |

Response Format

// Success
{
  "data": { "id": 1, "name": "John" },
  "meta": { "timestamp": "2024-01-15T10:00:00Z" }
}

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

// Error
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [{ "field": "email", "message": "Required" }]
  }
}

Query Parameters

GET /users?status=active&sort=-createdAt&page=1&limit=20
GET /users?fields=id,name,email
GET /users?include=posts,profile
GET /users?filter[age][gte]=18

When NOT to Use This Skill

GraphQL API design (use graphql skill)
tRPC type-safe APIs (use trpc skill)
OpenAPI specification writing (use openapi skill)
Real-time APIs requiring WebSockets or SSE
APIs requiring complex nested queries (consider GraphQL)

Anti-Patterns

| Anti-Pattern | Why It's Bad | Solution | |--------------|--------------|----------| | Using verbs in URLs (/getUser, /createOrder) | Not RESTful, violates resource naming | Use HTTP methods on nouns (GET /users, POST /orders) | | Returning 200 for errors | Misleading, breaks HTTP semantics | Use appropriate 4xx/5xx status codes | | Not versioning API | Breaking changes affect all clients | Use URL or header versioning (/v1/, /v2/) | | Exposing database IDs directly | Security risk, implementation leak | Use UUIDs or opaque identifiers | | No pagination on large collections | Performance issues, timeouts | Implement cursor or offset pagination | | Ignoring HTTP caching headers | Poor performance, unnecessary load | Use ETag, Cache-Control, Last-Modified | | Using GET for state-changing operations | Security risk, breaks REST principles | Use POST, PUT, PATCH, DELETE | | Inconsistent response formats | Client confusion, integration issues | Standardize on JSON envelope format | | Missing rate limiting | API abuse, resource exhaustion | Implement rate limiting with 429 responses |

Quick Troubleshooting

| Issue | Possible Cause | Solution | |-------|----------------|----------| | 401 Unauthorized | Missing or invalid auth token | Check Authorization header, verify token | | 403 Forbidden | Valid auth but insufficient permissions | Check user roles, verify access control | | 404 Not Found | Resource doesn't exist or wrong path | Verify endpoint URL, check resource ID | | 409 Conflict | Resource already exists or state conflict | Check uniqueness constraints, handle idempotency | | 422 Unprocessable Entity | Validation failed | Check request body, validate against schema | | 429 Too Many Requests | Rate limit exceeded | Implement backoff, check rate limit headers | | 500 Internal Server Error | Server-side bug or crash | Check server logs, add error handling | | CORS errors | Missing CORS headers | Configure CORS middleware with allowed origins | | Slow API responses | No pagination, N+1 queries | Add pagination, optimize database queries |

Production Readiness

Security Configuration

// Input validation and sanitization
import { z } from 'zod';

const CreateUserSchema = z.object({
  name: z.string().min(1).max(100).trim(),
  email: z.string().email().toLowerCase(),
  age: z.number().int().min(0).max(150).optional(),
});

// Validate request body
app.post('/users', async (req, res) => {
  const result = CreateUserSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(400).json({
      error: { code: 'VALIDATION_ERROR', details: result.error.issues },
    });
  }
  // Use result.data (validated and transformed)
});

// SQL injection prevention - always use parameterized queries
// NEVER: `SELECT * FROM users WHERE id = '${userId}'`
// GOOD: Use ORM or prepared statements

Rate Limiting

import rateLimit from 'express-rate-limit';

// Different limits for different endpoints
const standardLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100,
  standardHeaders: true,
  message: { error: { code: 'RATE_LIMIT_EXCEEDED' } },
});

const authLimiter = rateLimit({
  windowMs: 60 * 60 * 1000, // 1 hour
  max: 5, // Strict for auth endpoints
  skipSuccessfulRequests: true,
});

app.use('/api', standardLimiter);
app.use('/api/auth/login', authLimiter);

API Versioning

// URL versioning (recommended for breaking changes)
app.use('/api/v1', v1Router);
app.use('/api/v2', v2Router);

// Header versioning (for minor versions)
app.use('/api', (req, res, next) => {
  const version = req.headers['api-version'] || '1.0';
  req.apiVersion = version;
  next();
});

// Sunset header for deprecated endpoints
app.get('/api/v1/legacy', (req, res) => {
  res.set('Sunset', 'Sat, 01 Jun 2025 00:00:00 GMT');
  res.set('Deprecation', 'true');
  // ... handle request
});

Pagination

// Cursor-based pagination (recommended for large datasets)
interface PaginatedResponse<T> {
  data: T[];
  meta: {
    nextCursor: string | null;
    hasMore: boolean;
  };
}

app.get('/users', async (req, res) => {
  const cursor = req.query.cursor as string | undefined;
  const limit = Math.min(parseInt(req.query.limit as string) || 20, 100);

  const users = await db.users.findMany({
    take: limit + 1, // Fetch one extra to check if there's more
    cursor: cursor ? { id: cursor } : undefined,
    orderBy: { createdAt: 'desc' },
  });

  const hasMore = users.length > limit;
  const data = hasMore ? users.slice(0, -1) : users;

  res.json({
    data,
    meta: {
      nextCursor: hasMore ? data[data.length - 1].id : null,
      hasMore,
    },
  });
});

Error Handling

// Consistent error response format
interface APIError {
  error: {
    code: string;
    message: string;
    details?: unknown;
    requestId?: string;
  };
}

// Global error handler
app.use((err: Error, req: Request, res: Response, next: NextFunction) => {
  const requestId = req.headers['x-request-id'] as string;

  // Log error with context
  logger.error({
    err,
    requestId,
    path: req.path,
    method: req.method,
  });

  // Don't leak internal errors
  const statusCode = err instanceof HTTPError ? err.statusCode : 500;
  const message = statusCode === 500 ? 'Internal Server Error' : err.message;

  res.status(statusCode).json({
    error: {
      code: err.code || 'INTERNAL_ERROR',
      message,
      requestId,
    },
  });
});

Monitoring Metrics

| Metric | Alert Threshold | |--------|-----------------| | Request latency p99 | > 500ms | | Error rate (4xx) | > 5% | | Error rate (5xx) | > 1% | | Rate limit hits | > 100/min | | Request size | > 10MB |

CORS Configuration

import cors from 'cors';

const corsOptions = {
  origin: (origin, callback) => {
    const allowedOrigins = process.env.ALLOWED_ORIGINS?.split(',') || [];
    if (!origin || allowedOrigins.includes(origin)) {
      callback(null, true);
    } else {
      callback(new Error('Not allowed by CORS'));
    }
  },
  methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
  allowedHeaders: ['Content-Type', 'Authorization', 'X-Request-ID'],
  credentials: true,
  maxAge: 86400, // 24 hours
};

app.use(cors(corsOptions));

Request/Response Logging

import pino from 'pino-http';

app.use(pino({
  redact: ['req.headers.authorization', 'req.body.password'],
  serializers: {
    req: (req) => ({
      method: req.method,
      url: req.url,
      query: req.query,
    }),
    res: (res) => ({
      statusCode: res.statusCode,
    }),
  },
}));

Checklist

[ ] Input validation on all endpoints
[ ] Rate limiting configured
[ ] CORS properly restricted
[ ] API versioning strategy
[ ] Cursor-based pagination
[ ] Consistent error format
[ ] Request ID tracking
[ ] Structured logging
[ ] No sensitive data in URLs
[ ] Body size limits configured
[ ] Timeout handling
[ ] Health check endpoint