# Common API Design

Apply REST API conventions, HTTP semantics, status codes, versioning, pagination, and...

- Repository: https://github.com/HoangNguyen0403/agent-skills-standard (582 stars)
- Category: Design
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add HoangNguyen0403/agent-skills-standard --skill common-api-design -g -a claude-code -y`
Codex: `npx skills add HoangNguyen0403/agent-skills-standard --skill common-api-design -g -a codex -y`
Cursor: `npx skills add HoangNguyen0403/agent-skills-standard --skill common-api-design -g -a cursor -y`
Gemini CLI: `npx skills add HoangNguyen0403/agent-skills-standard --skill common-api-design -g -a gemini-cli -y`

## Description

Apply REST API conventions, HTTP semantics, status codes, versioning, pagination, and OpenAPI standards for any framework. Use when designing endpoints, choosing HTTP methods, implementing pagination, or writing OpenAPI specs.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Common API Design Standards

## **Priority: P1 (HIGH)**

## 🔧 HTTP Verb Semantics

- `GET` read-only, idempotent, never mutates state.
- `POST` create or trigger; `PUT` full replace; `PATCH` partial update; `DELETE` remove.
- Non-CRUD actions as sub-resources: `POST /orders/:id/cancel`.

## 📡 Status Code Correctness

- `200` success; `201` created (add `Location` header); `204` no body.
- `400` validation (with `details[]`); `401` unauthenticated; `403` unauthorized; `404` not found.
- `409` conflict; `422` business rule violation; `429` rate limit (add `Retry-After`); `500` unhandled.

## 📦 URL Design Rules

- **Lowercase, kebab-case**: `/user-profiles`, not `/UserProfiles` or `/user_profiles`.
- **Plural nouns**: `/orders`, `/products`. Not `/order`, `/getProducts`.
- **No verbs in paths** (except action sub-resources): `/orders/:id/cancel` ✅, `/cancelOrder` ❌.
- **Hierarchy**: Use nesting only up to 2 levels: `/users/:id/orders` ✅, `/users/:id/orders/:orderId/items/:itemId` ❌.

## 🔢 API Versioning

- **Strategy**: URL path versioning default: `/v1/users`, `/v2/users`.
- **Header versioning** (`Api-Version: 2`) acceptable for internal APIs.
- Never mix versions in same controller, each version gets its own route module.
- Support prev major ≥ 6 months after new release.
- Deprecation: `Deprecation: true` + `Sunset: <date>` headers when version will be retired.

## 📄 Pagination

- Prefer cursor-based (`cursor` + `limit`) for large/live datasets; offset only for small static ones.
- Default `limit: 20`, max `100`. Reject requests exceeding max.
- Response envelope: `{ data: [], pagination: { nextCursor, hasNextPage } }`.

## 📝 OpenAPI Contract

- Generate from code annotations, not hand-written YAML.
- Every API needs OpenAPI 3.1 spec.
- Include: request/response schemas, error shapes, auth requirements, examples.
- Review spec in PR, breaking changes need version bump.

## 🔒 API Security Baseline

The rest: https://github.com/HoangNguyen0403/agent-skills-standard/blob/HEAD/.agents/skills/common/common-api-design/SKILL.md