Agent skill · software engineering · affaan-m
api-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.
Why this skill is useful
Provides specific REST API design patterns and conventions that the AI wouldn't reliably generate on its own.
What it needs
About 7k tokens when loaded. Last updated 2026-08-06. 238,342 stars on the source repository.
What this skill does
API Design Patterns Conventions and best practices for designing consistent, developer-friendly REST APIs. When to Activate Designing new API endpoints Reviewing existing API contracts Adding pagination, filtering, or sorting Implementing error handling for APIs Planning API versioning strategy Building public or partner-facing APIs Resource Design URL Structure Naming Rules HTTP Methods and Status Codes Method Semantics Method Idempotent Safe Use For -------- ----------- ------ --------- GET Yes Yes Retrieve resources POST No No Create resources, trigger actions PUT Yes No Full replacement of a resource PATCH No No Partial update of a resource DELETE Yes No Remove a resource PATCH can be made idempotent with proper implementation Status Code Reference Common Mistakes Response Format Success Response Collection Response (with Pagination) Error Response Response Envelope Variants Pagination Offset-Based (Simple) Pros: Easy to implement, supports "jump to page N" Cons: Slow on large offsets (OFFSET 100000), inconsistent with concurrent inserts Cursor-Based (Scalable) Pros: Consistent performance regardless of position, stable with concurrent inserts Cons: Cannot jump to arbitrary page, cursor is opaque When to Use Which Use Case Pagination Type ---------- ---------------- Admin dashboards, small datasets (<10K) Offset Infinite scroll, feeds, large datasets Cursor Public APIs Cursor (default) with offset (optional) Search results Offset (users expect page numbers) Filtering, Sorting, and Search Filtering Sorting Full-Text Search Sparse Fieldsets Authentication and Authorization Token-Based Auth Authorization Patterns Rate Limiting Headers Rate Limit Tiers Tier Limit Window Use Case ------ ------- -------- ---------- Anonymous 30/min Per IP Public endpoints Authenticated 100/min Per user Standard API access Premium 1000/min Per API key Paid API plans Internal 10000/min Per service Service-to-service Versioning URL Path Versioning (Recommended) Pros: Explicit, easy to ro …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills affaan-m/api-design--7d7bda