api-design-principles
Installation
SKILL.md
Iron Law
NO API ENDPOINT DESIGN WITHOUT READING reference/rest-design-principles.md FIRST — HTTP semantics, status codes, idempotency, and caching strategies must be agreed before writing implementation code
API Design Principles
Stack-agnostic REST design principles for APIs built with Python FastAPI, NestJS 11.x, or Spring Boot WebFlux 3.5.x. Use this skill during the design phase — before writing controllers or route handlers.
When to Use
- Designing new REST endpoints from scratch
- Reviewing whether existing endpoints follow REST conventions
- Choosing a pagination strategy (offset vs cursor)
- Adding idempotency keys to mutation endpoints
- Designing caching strategy (ETags, Cache-Control)
- Designing bulk/batch endpoints with partial failure handling
- Running the pre-implementation API design checklist