api-design

Design and review REST APIs for stable contracts and predictable client behavior.

Updated Mar 28, 2026
One-click install
npx skills add https://github.com/mechemsi/claude-template --skill api-design-mechemsi
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/mechemsi/claude-template/tree/main/skills/api-design
Command: npx skills add https://github.com/mechemsi/claude-template --skill api-design-mechemsi

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Designing RESTful APIs that act as stable contracts, reducing breaking changes and improving client usability.

Core Features & Use Cases

  • REST resource modeling and consistent URL design.
  • HTTP method semantics, status codes, pagination, filtering, and versioning.
  • Guidance for idempotency, error envelopes, authentication, and backward compatibility across APIs.

Quick Start

Draft a concise REST contract for a new resource and log it in your API design document.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design a REST API that supports safe versioning and backward compatibility?

REST API versioning ensures stable contracts by applying consistent URL shapes and backward compatibility rules, preventing breaking changes when evolving endpoints across services. It guides safe resource modeling and predictable client behavior during updates.

What is the best way to handle pagination and filtering in HTTP REST APIs?

Pagination and filtering in REST APIs manage large data sets by applying consistent URL design and HTTP method semantics. This approach ensures predictable client behavior and stable contracts when querying resources across services.

How do I implement idempotent operations in a REST API?

Idempotent operations in a REST API ensure predictable client behavior by allowing safe retries without duplicate side effects. Designing stable contracts requires clear guidance on HTTP methods and status codes for idempotent resource modeling.

What HTTP status codes and error envelopes should I use for consistent REST API error handling?

Consistent REST API error handling requires standardized HTTP status codes and a uniform error envelope. Applying these design principles ensures stable contracts and predictable client behavior across all service endpoints.