| name | api-design-principles |
| description | Use before designing any REST API endpoint — covers URL structure, HTTP method semantics, pagination, caching, idempotency, and bulk operations across Python FastAPI, NestJS 11.x, and Spring Boot WebFlux 3.5.x. Complements openapi-spec-generation (spec format) and stack-specific implementation skills (code patterns). |
| allowed-tools | Read |
| metadata | {"triggers":"REST API design, API versioning, idempotency key, ETag caching, bulk operations, pagination pattern, API checklist, URL design, HTTP methods, REST principles, CORS, rate limiting header","related-skills":"openapi-spec-generation, java-spring-api, nestjs-api, python-dev, architecture-design","domain":"api-architecture","role":"specialist","scope":"design","output-format":"specification"} |
| last-reviewed | 2026-03-14 |
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
How This Skill Relates to Others
| Skill | Scope |
|---|
| api-design-principles (this skill) | Design phase — REST semantics, patterns, checklist |
| openapi-spec-generation | Documentation phase — OpenAPI 3.1 spec, developer guide |
| java-spring-api | Implementation — Spring WebFlux controllers, services |
| nestjs-api | Implementation — NestJS modules, controllers, DTOs |
| python-dev | Implementation — FastAPI routes, Pydantic models |
Process
Step 1: Run the Pre-Implementation Checklist
Read assets/api-design-checklist.md before designing any endpoint. Focus on:
- Resource naming and URL structure
- HTTP method assignment
- Status codes per operation
- Pagination strategy choice
- Versioning strategy
Step 2: Apply REST Design Principles
Read reference/rest-design-principles.md for detailed patterns covering:
- URL structure and resource naming (plural nouns, shallow nesting)
- HTTP methods and correct status codes per operation type
- Pagination — offset-based vs cursor-based, with examples for all 3 stacks
- Versioning strategies (URL path recommended)
- Rate limiting headers (X-RateLimit-*)
- Authentication (Bearer token, 401 vs 403 distinction)
- Error response format (consistent structure across all 3 stacks)
- Caching — Cache-Control, ETags, conditional GET (304) — all 3 stacks
- Idempotency keys — mutation safety for payment and order endpoints — all 3 stacks
- Bulk operations — batch endpoints with 207 Multi-Status partial failure — all 3 stacks
- CORS configuration — all 3 stacks
- Health and monitoring endpoints
Step 3: Document with OpenAPI
Once the design is finalized, hand off to openapi-spec-generation to generate the OpenAPI 3.1 spec.
Reference Files
| File | Content | Load When |
|---|
reference/rest-design-principles.md | URL structure, HTTP methods, pagination, caching, idempotency, bulk ops, CORS — examples for FastAPI, NestJS, Spring WebFlux | Designing new endpoints or reviewing REST compliance |
assets/api-design-checklist.md | 60-item pre-implementation checklist (REST only) with stack-specific items for all 3 backends | Before starting any new endpoint or reviewing an existing API |
Error Handling
Inconsistent status codes across endpoints: Follow the status code reference in reference/rest-design-principles.md section "HTTP Methods and Status Codes". All endpoints in a service must be consistent.
Pagination strategy mismatch: Choose offset-based for admin/report endpoints, cursor-based for real-time/feed endpoints. Document the choice — do not mix strategies within the same resource collection.
