api-design
REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.
Security Assessment
About api-design
This skill is a reference guide for designing consistent, developer-friendly REST APIs. It codifies the conventions that make an API predictable to consume: how to name and structure resource URLs, which HTTP methods and status codes to use for each operation, how to shape success and error response bodies, and how to add pagination, filtering, sorting, and search. It solves the recurring problem of ad-hoc, inconsistent API design by giving teams a single opinionated rulebook to follow when creating or reviewing endpoints.
The content is organized as concrete good-versus-bad examples. It covers resource naming (plural, kebab-case nouns; nested sub-resources for ownership), the semantics of GET/POST/PUT/PATCH/DELETE, a full status-code reference spanning success, client-error, and server-error ranges, and common mistakes such as returning 200 for everything. It documents response envelopes with data wrappers, pagination metadata and links, and structured field-level error objects. Pagination guidance contrasts offset-based and cursor-based approaches with pros, cons, and when to use each, and the skill also touches filtering syntax, sorting, sparse fieldsets, and token-based authentication headers.
It is aimed at backend engineers, API designers, and reviewers building public, partner-facing, or internal REST services. Typical use cases include designing new endpoints, reviewing an existing API contract, adding pagination or filtering to a collection endpoint, standardizing error handling, or planning a versioning strategy. It is purely advisory reference material and does not run code.
FAQ
What does this skill provide?
A set of REST API design conventions and best practices covering resource naming, HTTP methods, status codes, response formats, pagination, filtering, sorting, search, and token-based authentication, presented as good-versus-bad examples.
When should I activate it?
When designing new API endpoints, reviewing existing API contracts, adding pagination/filtering/sorting, implementing API error handling, planning versioning, or building public or partner-facing APIs.
Is it tied to a specific language or framework?
No. The guidance is framework-agnostic; examples use generic HTTP and JSON with some TypeScript interface snippets, so the conventions apply to any REST stack.
Does it run any code or tools?
No. It is a reference document that guides design decisions; it does not execute scripts or call external services.
What pagination approach does it recommend?
It presents both offset-based and cursor-based pagination with tradeoffs, recommending cursor-based as the default for public APIs and large datasets, and offset-based for admin dashboards and page-numbered search results.
Install api-design
Quick Setup:
- Copy the skill folder to
.claude/skills/ - Claude will automatically detect and use the skill
Repository
affaan-m/ecc