Skip to content
Skills Library
Programming · Building & coding

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.

Licence
MIT
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

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

  1. Priority: P1 (HIGH)
  2. 🔧 HTTP Verb Semantics
  3. 📡 Status Code Correctness
  4. 📦 URL Design Rules
  5. 🔢 API Versioning
  6. 📄 Pagination
  7. 📝 OpenAPI Contract
  8. 🔒 API Security Baseline
  9. Anti-Patterns
  10. References
Original SKILL.md headings · 63 lines, 397 words
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

RepositoryScoreLicence
This page · HoangNguyen0403/agent-skills-standard100MIT
HoangNguyen0403/agent-skills-standard100MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.