api-design-principles

---
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.

More agent context in kumaran-is/claude-code-onboarding

157 other files this repository gives its agents, the first 60 shown.