# API

> Design and scaffold APIs with contracts, validation, error handling, tests, documentation, and consumer impact awareness.

- Skill: `arogyareddy/api` (Agent Skill)
- Install (CLI): `npx skillmds@latest add arogyareddy/api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/arogyareddy/api/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: arogyareddy (https://skillmd.com/u/arogyareddy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/arogyareddy/api

---


# API

Use this for REST, RPC, GraphQL, route handlers, service layers, and request/response design.

## Workflow
1. Clarify the contract: inputs, outputs, auth, errors, idempotency, pagination, filtering.
2. Define request and response types.
3. Add validation at the boundary.
4. Keep handler, service, and persistence concerns separated.
5. Implement typed error handling and consistent status codes.
6. Add tests for success, validation failure, auth failure, and service errors.
7. Update docs and client usage.

## Architecture rules
- Thin controllers, rich services.
- Validate early.
- Keep domain logic out of transport glue.
- Design backward-compatible changes where possible.

## Output format
- Proposed contract
- Suggested file layout
- Implementation notes
- Tests required
- Breaking change risk