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.
1---2name: api-design-principles3description: 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).4---56## Iron Law78**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**910# API Design Principles1112Stack-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.1314## When to Use1516- Designing new REST endpoints from scratch17- Reviewing whether existing endpoints follow REST conventions18- Choosing a pagination strategy (offset vs cursor)19- Adding idempotency keys to mutation endpoints20- Designing caching strategy (ETags, Cache-Control)21- Designing bulk/batch endpoints with partial failure handling22- Running the pre-implementation API design checklist2324## How This Skill Relates to Others2526| Skill | Scope |27|-------|-------|28| **api-design-principles** (this skill) | Design phase — REST semantics, patterns, checklist |29| **openapi-spec-generation** | Documentation phase — OpenAPI 3.1 spec, developer guide |30| **java-spring-api** | Implementation — Spring WebFlux controllers, services |31| **nestjs-api** | Implementation — NestJS modules, controllers, DTOs |32| **python-dev** | Implementation — FastAPI routes, Pydantic models |3334## Process3536### Step 1: Run the Pre-Implementation Checklist3738Read `assets/api-design-checklist.md` before designing any endpoint. Focus on:39- Resource naming and URL structure40- HTTP method assignment41- Status codes per operation42- Pagination strategy choice43- Versioning strategy4445### Step 2: Apply REST Design Principles4647Read `reference/rest-design-principles.md` for detailed patterns covering:48- URL structure and resource naming (plural nouns, shallow nesting)49- HTTP methods and correct status codes per operation type50- Pagination — offset-based vs cursor-based, with examples for all 3 stacks51- Versioning strategies (URL path recommended)52- Rate limiting headers (X-RateLimit-*)53- Authentication (Bearer token, 401 vs 403 distinction)54- Error response format (consistent structure across all 3 stacks)55- **Caching** — Cache-Control, ETags, conditional GET (304) — all 3 stacks56- **Idempotency keys** — mutation safety for payment and order endpoints — all 3 stacks57- **Bulk operations** — batch endpoints with 207 Multi-Status partial failure — all 3 stacks58- CORS configuration — all 3 stacks59- Health and monitoring endpoints6061### Step 3: Document with OpenAPI6263Once the design is finalized, hand off to `openapi-spec-generation` to generate the OpenAPI 3.1 spec.6465## Reference Files6667| File | Content | Load When |68|------|---------|-----------|69| `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 |70| `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 |7172## Error Handling7374**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.7576**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.
kumaran-is