Api Design Principles

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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kumaran-is
• Source: kumaran-is/claude-code-onboarding
• License: MIT

Install and usage instructions live in the source repository linked above.