skills.rest
aman-2709
aman-2709COMMUNITY
Explore all skills by this author →
GitHub

api-design

Design REST APIs with resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting.

12|2|Updated Mar 22, 2026
Search Tags:#versioning#rest#error-handling#rate-limiting#pagination#api-design#response-format
One-click install
npx skills add https://github.com/aman-2709/superpowers-ecc --skill api-design-aman-2709
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/aman-2709/superpowers-ecc/tree/main/skills/api-design
Command: npx skills add https://github.com/aman-2709/superpowers-ecc --skill api-design-aman-2709

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Inconsistent or poorly designed REST APIs lead to developer confusion, fragile integrations, and increased maintenance costs; this Skill provides clear conventions and guardrails to create predictable, scalable, and developer-friendly APIs.

Core Features & Use Cases

  • Resource and URL conventions: guidance on pluralization, kebab-case, and when to model nested resources versus top-level endpoints.
  • HTTP semantics & status codes: recommendations for method usage, correct success and error codes, and structured error payloads.
  • Pagination, filtering, and rate limiting: patterns for offset and cursor pagination, query parameter filtering, sorting, and headers for rate limit reporting.
  • Use Case: Review a public users API to select URL versioning, choose cursor pagination for the user feed, define error formats, and add rate limit headers before release.

Quick Start

Use the api-design skill to review a draft endpoint and produce a concise REST specification that includes resource names, HTTP methods, status codes, pagination strategy, authentication requirements, and error formats.

Frequently Asked Questions about api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is the best way to design REST API pagination and filtering?▼

REST API error handling requires returning appropriate HTTP status codes alongside structured error objects. This ensures predictable API responses, allowing clients to programmatically parse failures and developers to debug integration issues without guessing the error format.

How do I structure REST API URLs for nested resources?▼

REST API versioning should be planned using URL versioning for public or partner-facing APIs. This strategy ensures backward compatibility and predictable endpoint behavior during contract evolution, allowing clients to migrate gradually without breaking existing integrations.

How do I implement REST API rate limiting headers?▼

REST API status codes must follow HTTP semantics, using correct success codes like 200 or 201 and appropriate error codes like 404 or 422. This ensures predictable API contracts and eliminates developer confusion when integrating endpoints.

When should I use cursor pagination over offset pagination in REST APIs?▼

Reviewing a draft REST API endpoint produces a concise specification including resource names, HTTP methods, status codes, and pagination strategy. This specification ensures the endpoint follows HTTP semantics and includes authentication and rate limiting requirements before release.

Related Skills

Explore More Software Engineering Skills→
coaguscoagus
2

rest-api-design

Define REST API guidelines for HTTP semantics, error handling, and versioning.

Community
Advanced
Adelie-SquadAdelie-Squad
17

api-developer

Design API contracts and generate OpenAPI 3.0 documentation.

Official
Advanced
Oruga420Oruga420

api-design

Design REST API conventions for resource naming, HTTP methods, and pagination.

Community
Advanced
reactivereactive
2.0k

rdc-rest

Define type-safe REST APIs with schema-driven normalization and caching.

Official
Advanced