Design REST APIs with Best Practices

This skill designs well-structured, scalable REST APIs - resource-based URI design, HTTP method and status-code conventions, versioning strategy, request/response structure, security, and OpenAPI documentation. Resource-based design favors nouns over verbs and hierarchical URIs (GET /api/v1/users/123/orders/456 over GET /api/v1/getUserOrder/123/456), with consistent plural-noun collection naming, filtering and pagination query parameters (?page=2&limit=20&sort=created_at:desc), and URL-path versioning (/api/v1/users, /api/v2/users) as the recommended strategy over header or query-parameter versioning.

HTTP methods map to specific status codes: GET returns 200/404, POST returns 201/400, PUT returns 200/201/404, and PATCH/DELETE return 200/204/404. Response structure wraps data in a data envelope with links and meta (version, timestamp, or pagination totals), while errors follow a structured format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "code": "INVALID_FORMAT",
        "message": "Email format is invalid"
      }
    ]
  },
  "meta": {
    "request_id": "req_123456789",
    "timestamp": "2024-01-15T10:30:00Z"
  }
}

Security guidance covers Bearer-token authentication as the recommended pattern (versus API keys or Basic Auth over HTTPS only), and required security headers (X-Content-Type-Options: nosniff, X-Frame-Options: DENY, X-XSS-Protection, Strict-Transport-Security). An OpenAPI 3.0.3 specification example documents a /users GET (paginated, capped at a maximum limit of 100) and POST endpoint with request/response schemas and a Bearer JWT security scheme. Further best practices cover content negotiation (Content-Type and Accept headers, supporting JSON and XML), rate-limiting headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, a 429 response with retry_after), caching headers (Cache-Control, ETag, Last-Modified, conditional requests via If-None-Match/If-Modified-Since), and documentation/testing practices - comprehensive docs with request/response samples, /health and /status endpoints, consistent error codes, and correlation IDs for logging.

Authentication-header examples show the concrete format for each scheme: Authorization: Bearer eyJhbGci... for Bearer tokens, X-API-Key: your-api-key-here for API keys, and Authorization: Basic dXNlcjpwYXNz for Basic Auth (flagged HTTPS-only). Request-body examples show a nested POST /api/v1/users payload with a user object carrying email, first_name, last_name, and a preferences sub-object, and a PATCH example updating only first_name and preferences.newsletter to illustrate partial updates.

Use it when designing or reviewing a REST API's resource structure, versioning, request/response format, security headers, rate limiting, caching, or OpenAPI specification. It is not a GraphQL or gRPC API-design guide - it is scoped specifically to RESTful HTTP API conventions.

Given an API domain and its resources, it produces resource URI structures and a collection-response shape wrapping a data array alongside meta totals (total, page, per_page, total_pages) and links for self/next/last pagination, plus the security, rate-limiting, and caching headers to apply.

The OpenAPI 3.0.3 example reuses schemas via $ref components (UserListResponse, CreateUserRequest) rather than inlining them per endpoint, and declares its Bearer scheme under securitySchemes as an HTTP bearer scheme with bearerFormat: JWT - letting the same schema and security definitions be referenced across multiple endpoints in one spec.

Backend and API developers designing or documenting a RESTful HTTP API.