skills.rest
gugug168
gugug168COMMUNITY
Explore all skills by this author →
GitHub

api-design

Define REST API conventions for naming, methods, status codes, and pagination.

Updated Feb 5, 2026
Search Tags:#versioning#error handling#api design#rest api#pagination#http status codes#api naming
One-click install
npx skills add https://github.com/gugug168/claudecode-tutorial --skill api-design-gugug168
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/gugug168/claudecode-tutorial/tree/main/everything-claude-code-learning/02-Skills/api-design
Command: npx skills add https://github.com/gugug168/claudecode-tutorial --skill api-design-gugug168

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill provides clear conventions and practical best practices to eliminate ambiguity when designing REST APIs, ensuring consistent resource naming, HTTP method semantics, status codes, pagination, filtering, error responses, versioning, and rate limiting so clients and servers interoperate reliably.

Core Features & Use Cases

  • Resource naming & URL structure: guidance on using nouns, plurals, kebab-case, nested resources, and avoiding verbs in endpoints.
  • HTTP semantics & status codes: mapping methods to intent (GET/POST/PUT/PATCH/DELETE) and recommended status code usage for success, client, and server errors.
  • Pagination & filtering: patterns for offset and cursor pagination with pros and cons, plus query-based filtering and sorting.
  • Error response schema & versioning: standardized error payloads with codes/messages/details, versioning strategies, and a pre-release checklist (validation, auth, rate limits).

Quick Start

Use this skill to review a proposed endpoint such as /api/v1/users to confirm naming, method semantics, response formats, error structure, and an appropriate pagination strategy.

Frequently Asked Questions about api-design

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

FAQPage Schema
What are the best practices for REST API resource naming and URL structure?▼

REST API resource naming should use plural nouns, kebab-case, and nested resources while avoiding verbs in endpoints to ensure consistent URL structure and reliable client-server interoperability.

How do I design error responses and handle HTTP status codes in a REST API?▼

Design REST API error responses using standardized payloads with codes, messages, and details, while mapping HTTP status codes accurately to success, client errors, and server errors for clear communication.

When should I use offset pagination versus cursor pagination in an API?▼

Use offset or cursor pagination based on your specific needs; offset is simpler for random access, while cursor pagination handles large datasets more efficiently during sequential API traversal.

What should be included in a REST API pre-release checklist for versioning and rate limiting?▼

A REST API pre-release checklist should include schema validation, authentication, rate limiting configuration, and versioning strategies to ensure public or partner-facing endpoints are robust and reliable.

Can this skill review an existing endpoint like /api/v1/users for method semantics and response formats?▼

Yes, you can use this skill to review proposed endpoints like /api/v1/users to confirm naming, HTTP method semantics, response formats, error structures, and appropriate pagination strategy.

Related Skills

Explore More Software Engineering Skills→
felvieirafelvieira
22

backend-api

Define API contracts and data models for Node.js backend applications.

Community
Advanced
patricio0312revpatricio0312rev
5

api-docs-generator

Generate OpenAPI documentation and multi-language SDKs from YAML or JSON specifications.

Community
Advanced
Oruga420Oruga420

api-design

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

Community
Advanced
Camilo8902Camilo8902

rest-to-graphql-migrator

Migrate REST APIs to GraphQL incrementally using schema stitching and REST data source wrappers.

Community
Advanced