api-design

Design REST APIs with patterns for naming, status codes, pagination, and versioning.

2|1|Updated Mar 4, 2026
One-click install
npx skills add https://github.com/cncoder/oneclaw --skill api-design-cncoder
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/cncoder/oneclaw/tree/main/skills/api-design
Command: npx skills add https://github.com/cncoder/oneclaw --skill api-design-cncoder

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

REST API design patterns help teams build consistent, scalable interfaces by standardizing resource naming, responses, and versioning.

Core Features & Use Cases

  • Resource Naming: kebab-case endpoints with plural nouns for clarity and consistency.
  • HTTP Semantics: standardized methods, status codes, error formats, and response envelopes.
  • Lifecycle & Versioning: pagination, filtering, sorting, versioning strategies, and rate limiting.
  • Real-world Example: apply patterns to a users resource with nested relationships and documented errors.

Quick Start

Run a design audit of your existing API contracts and apply the patterns to a new endpoint.

Frequently Asked Questions about api-design

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

FAQPage Schema
What's the best way to design REST APIs that scale cleanly?

To design REST APIs that scale cleanly, standardize resource naming with kebab-case and plural nouns, apply correct HTTP semantics, and implement robust pagination, error handling, and versioning strategies.

How do I handle pagination and filtering in a REST API?

Handle REST API pagination and filtering by applying standardized lifecycle patterns that support sorting and slicing large datasets, ensuring consistent response formats and clear URL conventions for nested resource relationships.

What HTTP status codes and error formats should my REST API use?

Your REST API should use standardized HTTP status codes alongside structured error schemas and response envelopes to clearly communicate failures, ensuring clients receive consistent, predictable error handling across all endpoints.

How do I implement versioning and rate limiting for production REST services?

Implement REST API versioning and rate limiting by applying lifecycle patterns that manage endpoint changes securely over time, protecting production services from abuse while maintaining backward compatibility for existing clients.

Can I use these REST API patterns to audit my existing endpoint contracts?

Yes, you can run a design audit against your existing API contracts to check resource naming, HTTP semantics, and security considerations, applying the patterns to refactor endpoints and document errors effectively.

Why does consistent resource naming matter for REST API design?

Consistent REST API resource naming matters because using plural nouns and kebab-case endpoints creates clear, predictable URL conventions that make interfaces easier to consume, scale, and maintain across development teams.