# API Design

> Evaluates API endpoint design for RESTfulness, consistency, error handling, and documentation.

- Skill: `diegosouzapw/api-design-12` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/api-design-12`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/api-design-12/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/diegosouzapw/api-design-12

---


# API Design Evaluator

Evaluate API design output against these criteria.

## RESTfulness (25%)

- Are HTTP methods used correctly (GET for reads, POST for creation, PUT/PATCH for updates, DELETE for removal)?
- Are resource URLs noun-based and plural (/users, /orders, not /getUsers, /createOrder)?
- Are status codes appropriate (201 for creation, 204 for no content, 404 for not found)?
- Is the URL hierarchy logical (/users/:id/orders, not /user-orders)?
- Are query parameters used for filtering/sorting/pagination (not path segments)?
- Is HATEOAS considered where appropriate?
- For non-REST APIs (GraphQL, RPC): are equivalent conventions followed?

## Consistency (25%)

- Are naming conventions consistent (camelCase vs snake_case, chosen and stuck to)?
- Are response shapes consistent across endpoints (same envelope, same error format)?
- Are pagination patterns consistent (cursor vs offset, same parameter names)?
- Do similar operations behave similarly (all CRUD endpoints for all resources follow same pattern)?
- Are date formats consistent (ISO 8601)?
- Are ID formats consistent (UUID vs integer, same field name)?

## Error Responses (30%)

- Do error responses include a machine-readable error code?
- Do error responses include a human-readable message?
- Are validation errors specific (which field failed, why)?
- Are errors safe (no stack traces, internal paths, or SQL in production responses)?
- Are error codes documented and stable (clients can switch on them)?
- Is there a consistent error envelope (same shape for all errors)?
- Are rate limit errors informative (retry-after header)?
- Do 5xx responses avoid leaking implementation details?

## Documentation (20%)

- Are request/response schemas defined (OpenAPI, JSON Schema, or equivalent)?
- Are required vs optional fields clearly marked?
- Are example requests and responses provided?
- Are authentication requirements documented per endpoint?
- Are rate limits and quotas documented?
- Are breaking change policies documented (versioning strategy)?
- Is the documentation generated from code or kept in sync?

## Severity Guide

- **Blocker**: Wrong HTTP method semantics, error responses leaking internals, missing auth on sensitive endpoint
- **Important**: Inconsistent naming across endpoints, missing error codes, no pagination on list endpoints
- **Suggestion**: Minor naming improvements, additional examples, HATEOAS links