# Good
GET    /users/42
POST   /users

# Bad
GET    /getUsers
POST   /createUser

se one strategy and stick with it everywhere. Breaking changes must never be introduced to a stable version without a new prefix.

3. Consistent Naming

• JSON: camelCase (createdAt)
• URL paths: kebab-case (/user-orders)
• Query params: snake_case (?sort_by=name)

4. Use the Right HTTP Status Codes

Code	When
200	Successful GET, PUT, PATCH
201	Successful POST — include Location header
204	Successful DELETE
400	Validation failure
401	Missing/expired token
403	Authenticated but not permitted
404	Resource doesn't exist
409	Duplicate or state conflict
422	Valid syntax but semantic error
429	Rate limit — include Retry-After header

5. Consistent Error Responses

All error payloads must follow a uniform schema to enable automated client handling and centralized logging.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Email is required",
    "details": [
      {"field": "email", "reason": "must not be empty"}
    ],
    "requestId": "req_abc123"
  }
}

6. Pagination

Offset-based pagination degrades performance on large datasets. Use cursor-based pagination for consistent, performant traversal.

# Cursor-based (preferred for large datasets)
GET /users?cursor=eyJpZCI6NDJ9&limit=20
Response: {"data": [...], "nextCursor": "...", "hasMore": true}

7. Security Checklist

• Always HTTPS. No exceptions.
• Rate limit. 60 req/min per IP for unauthenticated users minimum.
• Validate Content-Type. Reject requests with wrong Content-Type.
• Never use Access-Control-Allow-Origin: * with credentials.
• Use OAuth2 or API keys. Never roll your own auth.
• Keep secrets out of responses. Password hashes, internal IDs, stack traces, server versions.

8. Always Have an OpenAPI Spec

Use OpenAPI 3.1 (Swagger). Stoplight, Redoc, and Swagger UI generate beautiful interactive docs from a single spec file. If your API doesn't have an OpenAPI spec, it's not production-ready.

Pitfall Guide

1. Verb-Driven Resource Naming: Using /getUsers or /createUser breaks REST semantics, forces clients to parse URLs for action intent, and prevents proper HTTP method mapping and caching strategies.
2. Inconsistent Versioning Strategies: Mixing URL (/v1), header (Accept: application/vnd.api.v1+json), and query parameter versioning creates routing complexity, breaks client SDK generation, and complicates backward compatibility management.
3. Misusing HTTP Status Codes: Returning 200 OK for errors or 404 for validation failures obscures failure modes, breaks automated retry logic, and complicates monitoring/alerting pipelines.
4. Leaking Sensitive Data in Error Payloads: Including stack traces, internal IDs, or password hashes in 4xx responses exposes attack surfaces, violates compliance standards (GDPR, SOC2), and aids reconnaissance attacks.
5. Ignoring Pagination Limits & Cursor Validation: Relying on offset/limit for large datasets causes performance degradation and inconsistent results during concurrent writes. Failing to enforce max_limit or validate cursor integrity enables DoS vectors.
6. Wildcard CORS with Credentials: Using Access-Control-Allow-Origin: * alongside Access-Control-Allow-Credentials: true is rejected by modern browsers and creates authentication bypass vulnerabilities in cross-origin requests.
7. Skipping Contract-First Development: Building APIs without an OpenAPI spec leads to documentation drift, manual testing overhead, incompatible client SDKs across teams, and delayed consumer onboarding.

Deliverables

• REST API Architecture & Contract Design Blueprint: A comprehensive architectural template covering routing conventions, versioning strategies, error schema definitions, pagination mechanics, security header configurations, and OpenAPI 3.1 structure. Includes decision matrices for choosing between URL, header, and content-type versioning.
• Pre-Production API Validation Checklist: A 42-point validation framework covering naming consistency, HTTP status code mapping, error payload compliance, pagination enforcement, security hardening (CORS, rate limiting, secret management), and automated documentation generation. Designed for CI/CD pipeline integration and peer review sign-offs.