common-api-design
/common-api-design
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.
- Author
- HoangNguyen0403 ↗
- Repository
- agent-skills-standard ↗
- Licence
- MIT
- Last repository change
- 12.11.2026
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
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.
Original author 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.
How it works
- Priority: P1 (HIGH)
- 🔧 HTTP Verb Semantics
- 📡 Status Code Correctness
- 📦 URL Design Rules
- 🔢 API Versioning
- 📄 Pagination
- 📝 OpenAPI Contract
- 🔒 API Security Baseline
- Anti-Patterns
- References
SKILL.md preview
---
name: common-api-design
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.
metadata:
triggers:
files:
- '**/*.controller.ts'
- '**/*.router.ts'
- '**/*.routes.ts'
- '**/routes/**'
- '**/controllers/**'
- '**/handlers/**'
keywords:
- rest api
- endpoint
- http method
- status code
- versioning
- pagination
- openapi
- api design
- api contract
---
# 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
- Require auth on all routes by default; use `@Public()` or equivalent opt-out.
- Validate and sanitize all query params, path params, and request bodies.
- Set `Content-Type: application/json` explicitly. Reject unexpected content types.
- Include `X-Content-Type-Options: nosniff` and `X-Frame-Options: DENY` headers.
## Anti-Patterns
- **No `GET` mutations**: Search engines and CDNs cache GET — mutating state catastrophic.
- **No 200 for errors**: `{ "success": false, "data": null }` with HTTP 200 breaks monitoring.
- **No deeply nested URLs**: Hard to document, version, and cache.
- **No breaking changes without versioning**: Removing/renaming fields in-place breaks consumers silently.
## References
- [URL Examples, Status Codes & Pagination Envelope](references/REFERENCE.md)
- [API Correctness & Contract Testing](../../quality-engineering/quality-engineering-api-testing/SKILL.md) — executable smoke, functional, contract, integration, and regression selection standards.
Files in this package (3)
- SKILL.md 4 KB
- evals/evals.json 9 KB
- references/REFERENCE.md 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · HoangNguyen0403/agent-skills-standard | 100 | MIT |
| HoangNguyen0403/agent-skills-standard | 100 | MIT |
Database snapshot: 13.11.2026 · package version e34b0323f15c (SHA-256 digest of the entire package)
Downloads in the last 30 days: 1 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100rest-api
REST API design principles. Covers resources, methods, and status codes. Use when designing or reviewing REST APIs. USE WHEN: user mentions "REST API", "RESTful", "HTTP methods", "status codes", "resource naming", "API endpoints", "pagination", "versioning", asks about "how to… - 95api-design
REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs. Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning. - 100api-design
REST API conventions covering URL structure, HTTP methods, status codes, pagination, filtering, error responses, and versioning. Use when designing or reviewing REST API endpoints, adding routes, or standardizing API error handling. - 100api-design
Designs HTTP REST API contracts: resources, status codes, pagination, errors and OpenAPI. Use when shaping a new API surface, turning verb-style endpoints into resources, choosing pagination or versioning, standardising error bodies, writing an openapi.yaml, or judging whether a… - 100api-design
REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs. Use when designing or reviewing REST endpoints, resource names, status codes, pagination, or versioning. - 100api-design-rest
Rules for designing and implementing HTTP/REST APIs. Use when creating or reviewing endpoints, request/response shapes, status codes, error formats, pagination, filtering, versioning, idempotency, rate limiting, or API documentation.