REST API

## Setup On first use, read `setup.md` for integration behavior and memory initialization. ## When to Use Use this skill when the user wants to design, implement, secure, test, and ship a REST API from scratch or harden an existing API for production. This skill covers contract-first design, endpoint conventions, authentication and authorization, persistence strategy, test plans, observability, and release checklists. ## Architecture Working memory lives in `~/rest-api/`. See `memory-template.md` for structure and status behavior. ``` ~/rest-api/ ├── memory.md # HOT: active API project context ├── contracts/ # WARM: OpenAPI specs and compatibility notes ├── decisions/ # WARM: ADR-style technical decisions ├── tests/ # WARM: test plans and quality gates ├── operations/ # WARM: runbooks and incident notes └── archive/ # COLD: closed projects and old versions ``` ## Quick Reference Load only what is needed for the current API task. | Topic | File | |-------|------| | Setup and activation behavior | `setup.md` | | Memory schema | `memory-template.md` | | Contract-first design | `api-contract.md` | | Endpoint conventions and errors | `endpoint-design.md` | | Auth and API security controls | `auth-and-security.md` | | Data model and migrations | `persistence-and-migrations.md` | | Test strategy and telemetry | `testing-and-observability.md` | | Pre-release readiness gate | `deployment-checklist.md` | ## Core Rules ### 1. Start From the Contract, Not the Controller Define resources, payload schemas, status codes, and error shapes in OpenAPI before writing handlers. If the contract is unclear, implementation speed creates rework and breaks clients. ### 2. Keep Endpoint Semantics Predictable Use stable naming, plural resources, and correct HTTP methods. Make idempotent behavior explicit for `PUT`, `DELETE`, and retryable `POST` operations. Predictable semantics reduce client bugs and support safer retries. ### 3. Enforce Security by Default Require authentication on non-public endpoints, apply authorization checks at resource boundary, validate input strictly, and sanitize output. Never rely on frontend validation as a security control. ### 4. Design for Failure Paths First Specify error classes, timeout strategy, rate-limit behavior, and fallback expectations before scaling happy-path code. APIs fail in production at edges, not in demos. ### 5. Make Data Changes Backward Compatible Use additive schema migrations first, backfill data safely, and only remove old fields after client migration windows close. Breaking database or response changes without rollout planning cause outages. ### 6. Test Contract, Behavior, and Operations Cover OpenAPI contract validation, integration tests against real infrastructure, and end-to-end tests for critical user journeys. Unit tests alone do not prove API reliability. ### 7. Ship With Observability and Runbooks Expose request metrics, structured errors, trace identifiers, and health indicators. Document recovery steps for known failure modes. If an API cannot be observed, it cannot be operated safely. ## Common Traps - Building endpoints before defining response and error contracts -> incompatible clients and patchwork fixes. - Mixing auth, business logic, and transport concerns in handlers -> brittle code and hidden security gaps. - Treating pagination and filtering as optional -> unstable list endpoints and expensive queries. - Returning inconsistent error bodies across services -> poor client DX and weak automation. - Shipping without migration rollback steps -> long incidents when a release fails. ## Security & Privacy **Data that leaves your machine:** - None by default. **Data that stays local:** - API project context and decisions under `~/rest-api/`. **This skill does NOT:** - Call undeclared external endpoints by default. - Store secrets automatically. - Modify infrastructure without explicit user instruction. ## Related Skills Install with `clawhub install <slug>` if user confirms: - `backend` - System design and backend architecture decisions. - `auth` - Authentication, session strategy, and credential safety. - `http` - HTTP protocol details and request-response behavior. - `api` - Third-party API integration references. ## Feedback - If useful: `clawhub star rest-api` - Stay updated: `clawhub sync`