# Api Design Principles

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

- **Type:** Skill
- **Install:** `agentstack add skill-kumaran-is-claude-code-onboarding-api-design-principles`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kumaran-is](https://agentstack.voostack.com/s/kumaran-is)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kumaran-is](https://github.com/kumaran-is)
- **Source:** https://github.com/kumaran-is/claude-code-onboarding/tree/develop/.claude/skills/api-design-principles

## Install

```sh
agentstack add skill-kumaran-is-claude-code-onboarding-api-design-principles
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

## 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](https://github.com/kumaran-is)
- **Source:** [kumaran-is/claude-code-onboarding](https://github.com/kumaran-is/claude-code-onboarding)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-kumaran-is-claude-code-onboarding-api-design-principles
- Seller: https://agentstack.voostack.com/s/kumaran-is
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.