rest-api-design

name	rest-api-design
description	>- Use when this capability is needed.

REST API Design

Guide design and review of HTTP JSON APIs that follow REST-oriented conventions. Combine checklist-driven feedback with actionable recommendations.

If the user needs test cases for an existing endpoint, prefer the separate api-test-scenario-generator skill. This skill focuses on shape, semantics, and documentation of the API itself.

When this skill applies

Use for requests such as:

• "Review our REST API" / "Is this endpoint RESTful?"
• "How should we version or paginate?"
• "What status code and error body should we return?"
• "Improve this OpenAPI/Swagger spec"
• "Naming for paths and query parameters"

Out of scope

• GraphQL or tRPC design (different paradigms)
• Authoring a full OpenAPI file from scratch without user context (offer structure and sections instead)
• WebSocket or SSE real-time protocols as the primary topic
• Low-level infrastructure (load balancers, K8s) unless tied to API gateway or CORS

Optional: if the workspace has a documentation MCP, you may use it for framework-specific snippets; this skill does not require any MCP.

Inputs and outputs

Inputs (any combination):

• OpenAPI/Swagger YAML or JSON (snippet or path)
• List of routes with methods
• Free-form description of resources and operations

Outputs:

• Prioritized findings: must-fix (wrong HTTP semantics, security footguns) vs should-fix vs nice-to-have
• Concrete suggestions: path shape, method, status code, query names, response envelope, error shape
• Assumptions called out explicitly when the user did not specify domain rules

Review workflow

1. Resources and paths — Nouns, plural collection names, hierarchy with /, avoid verbs in URLs. Prefer shallow paths; use query filters instead of deep nesting when possible (/nodes?flowsheetId= vs four-level paths).
2. Methods — Map operations to GET/POST/PUT/PATCH/DELETE; know idempotency expectations.
3. Status codes — Use codes that match HTTP semantics; success vs client error vs server error.
4. Query layer — Filters, sort, sparse fieldsets, pagination parameters; consistent camelCase naming.
5. Pagination — Pick one documented strategy per API. Prefer cursor-based for very large or high-churn collections; use page + pageSize (or offset/limit) with clear response metadata when offset style is required. See references/detail.md.
6. Versioning — Prefer integer path segments (e.g. /v1/, /v2/). Avoid versioning only via query or ad-hoc headers as the sole mechanism.
7. Request bodies — JSON, clear field names, validation, PATCH for partial updates; avoid putting body fields in query for POST/PUT.
8. Errors — Meaningful messages, correct HTTP status; consider structured problem details (RFC 9457-style) with field-level errors for validation.
9. Documentation — OpenAPI: paths, operations, parameters, responses, auth, examples.

For anti-patterns, troubleshooting tables, production checklist, and Swagger/OpenAPI checklist detail, read references/detail.md when producing a full review.

Resource naming (quick reference)

# Collections (plural nouns)
GET    /users
POST   /users
GET    /users/{id}
PUT    /users/{id}
PATCH  /users/{id}
DELETE /users/{id}

# Nested resources (keep shallow)
GET    /users/{id}/posts
POST   /users/{id}/posts

# Prefer not: /getUsers, /createUser, /user (singular collection)

HTTP methods

Method	Typical use	Idempotent
GET	Read	Yes
POST	Create, actions	No
PUT	Replace full resource	Yes
PATCH	Partial update	Yes
DELETE	Remove	Yes

Common status codes

Code	Meaning	Typical use
200	OK	Successful GET, PUT, PATCH
201	Created	Successful POST creating a resource
204	No Content	Successful DELETE or empty success
400	Bad Request	Malformed request, generic client error
401	Unauthorized	Missing or invalid auth
403	Forbidden	Authenticated but not allowed
404	Not Found	Resource missing
409	Conflict	State conflict, duplicate
422	Unprocessable	Validation / semantic error (common convention)
429	Too Many Requests	Rate limited
500	Server Error	Unexpected server failure

Use 4xx for client-fixable issues and 5xx only for server-side failures. Do not return 200 with an error payload for failed operations.

Response shape (JSON)

Prefer a consistent envelope so clients can parse predictably:

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

For collections, include pagination metadata in meta (or a documented top-level object) consistent with your pagination strategy.

Errors (illustrative; align with your standard and RFC 9457 where applicable):

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [{ "field": "email", "message": "Invalid format" }]
  }
}

Query parameters (patterns)

GET /users?status=active&sort=-createdAt&page=1&pageSize=20
GET /users?fields=id,name,email
GET /products?category=electronics&price_lt=100

Document filter operators if you use suffixes like _lt, _gt, etc.

Pagination note (two valid styles)

• Cursor-based (often better at scale): cursor, limit, nextCursor / hasMore in response.
• Offset / page (common and simple): e.g. page, pageSize with totalItems, totalPages in the response.

Validate page ≥ 1 and pageSize within min/max; return clear error messages for out-of-range pagination (see detail reference).

Hard rules for reviews

• Call out verbs in URLs, GET for state changes, and wrong status codes as high priority.
• Prefer consistent naming (e.g. camelCase) across query and JSON fields unless the API already standardizes on snake_case—then enforce consistency, not mixed styles.
• Date/time in JSON: prefer ISO 8601 (e.g. 2024-09-15T08:00:00Z).
• Never expose secrets in URLs or logs; redact tokens in examples.

Related

• Deeper tables and checklists: references/detail.md

---

Source: dneprokos/skills-examples — distributed by TomeVault.