Claude Code rule For developers

API Design (rule)

Contributed by Rohit Ghumare (awesome-claude-code-toolkit)

Source: original file · added 2026-10-29

API Design

REST Conventions

  • Use plural nouns for resource paths: /users, /orders, /products.
  • Map HTTP methods to operations: GET (read), POST (create), PUT (full update), PATCH (partial update), DELETE (remove).
  • Use nested routes for relationships: /users/:id/orders not /getUserOrders.
  • Keep URLs lowercase with hyphens: /order-items not /orderItems.
  • Limit nesting to two levels. Beyond that, use query parameters or top-level routes.

Status Codes

  • 200 OK: Successful read or update.
  • 201 Created: Successful resource creation. Include Location header.
  • 204 No Content: Successful delete with no response body.
  • 400 Bad Request: Validation failure or malformed input.
  • 401 Unauthorized: Missing or invalid authentication.
  • 403 Forbidden: Authenticated but lacks permission.
  • 404 Not Found: Resource does not exist.
  • 409 Conflict: Duplicate or state conflict.
  • 422 Unprocessable Entity: Valid syntax but semantic errors.
  • 429 Too Many Requests: Rate limit exceeded. Include Retry-After header.
  • 500 Internal Server Error: Unhandled server failure. Never expose stack traces.

Versioning

  • Use URL path versioning for public APIs: /api/v1/users.
  • Use header versioning for internal APIs: Accept: application/vnd.api.v2+json.
  • Support the previous version for at least 6 months after deprecation.
  • Return a Deprecation header on sunset-path endpoints.

Pagination

  • Use cursor-based pagination for large or real-time datasets: ?cursor=abc&limit=20.
  • Use offset pagination only for small, static datasets: ?page=1&per_page=25.
  • Default limit: 20 items. Maximum limit: 100 items.
  • Return pagination metadata in the response: { data, meta: { cursor, hasMore, total } }.

Response Format

  • Consistent envelope: { data, error, meta } across all endpoints.
  • Error responses: { error: { code: "VALIDATION_ERROR", message: "...", details: [...] } }.
  • Use ISO 8601 for all timestamps: 2026-01-15T09:30:00Z.
  • Return null for absent optional fields, not missing keys.
  • Include requestId in all responses for traceability.

Rate Limiting

  • Public endpoints: 60 requests per minute.
  • Authenticated endpoints: 600 requests per minute.
  • Write endpoints: 30 requests per minute.
  • Return X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers.
Original source file (unmodified)

# API Design ## REST Conventions - Use plural nouns for resource paths: `/users`, `/orders`, `/products`. - Map HTTP methods to operations: GET (read), POST (create), PUT (full update), PATCH (partial update), DELETE (remove). - Use nested routes for relationships: `/users/:id/orders` not `/getUserOrders`. - Keep URLs lowercase with hyphens: `/order-items` not `/orderItems`. - Limit nesting to two levels. Beyond that, use query parameters or top-level routes. ## Status Codes - 200 OK: Successful read or update. - 201 Created: Successful resource creation. Include `Location` header. - 204 No Content: Successful delete with no response body. - 400 Bad Request: Validation failure or malformed input. - 401 Unauthorized: Missing or invalid authentication. - 403 Forbidden: Authenticated but lacks permission. - 404 Not Found: Resource does not exist. - 409 Conflict: Duplicate or state conflict. - 422 Unprocessable Entity: Valid syntax but semantic errors. - 429 Too Many Requests: Rate limit exceeded. Include `Retry-After` header. - 500 Internal Server Error: Unhandled server failure. Never expose stack traces. ## Versioning - Use URL path versioning for public APIs: `/api/v1/users`. - Use header versioning for internal APIs: `Accept: application/vnd.api.v2+json`. - Support the previous version for at least 6 months after deprecation. - Return a `Deprecation` header on sunset-path endpoints. ## Pagination - Use cursor-based pagination for large or real-time datasets: `?cursor=abc&limit=20`. - Use offset pagination only for small, static datasets: `?page=1&per_page=25`. - Default limit: 20 items. Maximum limit: 100 items. - Return pagination metadata in the response: `{ data, meta: { cursor, hasMore, total } }`. ## Response Format - Consistent envelope: `{ data, error, meta }` across all endpoints. - Error responses: `{ error: { code: "VALIDATION_ERROR", message: "...", details: [...] } }`. - Use ISO 8601 for all timestamps: `2026-01-15T09:30:00Z`. - Return `null` for absent optional fields, not missing keys. - Include `requestId` in all responses for traceability. ## Rate Limiting - Public endpoints: 60 requests per minute. - Authenticated endpoints: 600 requests per minute. - Write endpoints: 30 requests per minute. - Return `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers.

Our network