rest.yaml

# REST API Code Review Guidelines
# Comprehensive rules for HTTP methods, URLs, status codes, request/response, HATEOAS, and documentation

description: "Code review guidelines for RESTful API design covering HTTP semantics, resource naming, and best practices"
globs:
  - "**/*controller*"
  - "**/*handler*"
  - "**/*route*"
  - "**/*api*"
  - "**/*.ts"
  - "**/*.js"
  - "**/*.py"
  - "**/*.java"
  - "**/*.go"
  - "**/*.rb"
  - "**/openapi*.yaml"
  - "**/swagger*.yaml"

rules:
  # ============================================================================
  # HTTP METHODS RULES
  # ============================================================================

  - name: use-correct-http-verbs
    description: >
      Use HTTP methods according to their semantics: GET for retrieval, POST for creation,
      PUT for full replacement, PATCH for partial updates, DELETE for removal. HEAD for
      metadata, OPTIONS for capabilities. Never use POST for operations that should be GET.
    severity: high

  - name: ensure-get-idempotency
    description: >
      GET requests must be safe (no side effects) and idempotent. Never use GET to
      modify server state, create resources, or trigger actions. Side effects make
      caching impossible and violate HTTP semantics.
    severity: critical

  - name: ensure-put-delete-idempotency
    description: >
      PUT and DELETE must be idempotent - calling them multiple times produces the same
      result as calling once. PUT should replace the entire resource. Use PATCH for
      partial updates that may not be idempotent.
    severity: high

  - name: use-post-for-non-idempotent-actions
    description: >
      Use POST for non-idempotent operations like resource creation, complex actions,
      or operations that can't be expressed with standard methods. Consider using
      action-oriented sub-resources (e.g., /orders/123/cancel) for RPC-style operations.
    severity: medium

  # ============================================================================
  # URL DESIGN RULES
  # ============================================================================

  - name: use-nouns-for-resources
    description: >
      Use plural nouns for resource collections (/users, /orders). Avoid verbs in URLs;
      the HTTP method indicates the action. Resource names should be consistent and
      represent the domain model clearly.
    severity: high

  - name: maintain-resource-hierarchy
    description: >
      Express resource relationships through URL hierarchy (/users/123/orders).
      Limit nesting to 2-3 levels maximum. Deep nesting indicates potential design
      issues. Consider flattening with query parameters or separate endpoints.
    severity: medium

  - name: use-query-parameters-correctly
    description: >
      Use query parameters for filtering (?status=active), sorting (?sort=created_at),
      pagination (?page=2&limit=10), and field selection (?fields=id,name). Never use
      query parameters to identify resources - use path parameters instead.
    severity: medium

  - name: implement-api-versioning
    description: >
      Version APIs to allow evolution without breaking clients. Use URL path versioning
      (/v1/users), header versioning (Accept: application/vnd.api+json;version=1),
      or query parameter (?version=1). Be consistent across the entire API.
    severity: high

  - name: use-kebab-case-in-urls
    description: >
      Use lowercase letters and hyphens (kebab-case) in URLs (/user-profiles, not
      /userProfiles or /user_profiles). URLs are case-sensitive and should be
      consistent. Hyphens improve readability and SEO.
    severity: low

  # ============================================================================
  # STATUS CODES RULES
  # ============================================================================

  - name: use-appropriate-status-codes
    description: >
      Return accurate HTTP status codes: 200 for success, 201 for creation, 204 for
      no content, 400 for bad request, 401 for unauthorized, 403 for forbidden, 404
      for not found, 422 for validation errors, 500 for server errors.
    severity: high

  - name: distinguish-401-vs-403
    description: >
      Use 401 Unauthorized when authentication is missing or invalid. Use 403 Forbidden
      when authenticated but not authorized for the resource. Never use 404 to hide
      resources from unauthorized users unless specifically required for security.
    severity: medium

  - name: use-201-for-creation
    description: >
      Return 201 Created for successful POST requests that create resources. Include
      Location header pointing to the new resource. Return the created resource in
      the response body or provide a way to fetch it.
    severity: medium

  - name: use-204-for-no-content
    description: >
      Return 204 No Content for successful DELETE operations or updates that don't
      return data. Don't return a body with 204. Use 200 with body if the response
      contains useful information.
    severity: low

  - name: consistent-error-response-format
    description: >
      Use consistent error response structure across all endpoints. Include error code,
      message, and details. Structure: {"error": {"code": "VALIDATION_ERROR",
      "message": "...", "details": [...]}}. Document error codes in API documentation.
    severity: high

  # ============================================================================
  # REQUEST/RESPONSE RULES
  # ============================================================================

  - name: support-content-negotiation
    description: >
      Support Content-Type and Accept headers for format negotiation. Default to
      application/json. Return 415 Unsupported Media Type for unsupported Content-Type.
      Return 406 Not Acceptable for unsupported Accept values.
    severity: medium

  - name: implement-pagination
    description: >
      Paginate list endpoints that can return large datasets. Use limit/offset or
      cursor-based pagination. Include total count, next/previous links, and current
      page info. Default to reasonable page sizes (10-100 items).
    severity: high

  - name: support-filtering-and-sorting
    description: >
      Allow filtering via query parameters (?status=active&created_after=2024-01-01).
      Support sorting with direction (?sort=name:asc,created_at:desc). Validate
      filter/sort fields to prevent injection and errors.
    severity: medium

  - name: use-consistent-date-format
    description: >
      Use ISO 8601 format for all dates and timestamps (2024-01-15T10:30:00Z).
      Include timezone information, preferably UTC. Be consistent across all
      endpoints and document the format in API documentation.
    severity: medium

  - name: validate-request-bodies
    description: >
      Validate all request body fields. Return 400 Bad Request with detailed
      validation errors. Use JSON Schema or similar for validation. Include
      field name, constraint violated, and expected format in error details.
    severity: high

  # ============================================================================
  # HATEOAS RULES
  # ============================================================================

  - name: include-hypermedia-links
    description: >
      Include hypermedia links in responses to enable discoverability. Use _links
      or links field with rel and href. Common relations: self, next, prev, first,
      last, related resources. Links enable client navigation without hardcoded URLs.
    severity: low

  - name: use-standard-link-relations
    description: >
      Use IANA-registered link relations where applicable: self, next, prev, first,
      last, collection, item, edit, delete. Custom relations should be URIs or
      clearly documented. Consistent naming aids API understanding.
    severity: low

  # ============================================================================
  # DOCUMENTATION RULES
  # ============================================================================

  - name: maintain-openapi-specification
    description: >
      Document APIs using OpenAPI/Swagger specification. Include descriptions for
      endpoints, parameters, request/response schemas, and examples. Keep spec
      in sync with implementation. Generate documentation from spec.
    severity: high

  - name: provide-request-response-examples
    description: >
      Include realistic request and response examples in documentation. Cover
      success cases, error cases, and edge cases. Examples help developers
      understand expected formats better than schemas alone.
    severity: medium

  - name: document-error-codes
    description: >
      Document all error codes, their meanings, and possible solutions. Include
      which endpoints can return which errors. Error documentation helps clients
      implement proper error handling.
    severity: medium

  - name: maintain-api-changelog
    description: >
      Maintain changelog documenting API changes between versions. Note breaking
      changes, deprecations, new features, and bug fixes. Provide migration guides
      for breaking changes. Follow semantic versioning principles.
    severity: medium