api-design

Design REST APIs with consistent naming, semantics, and error handling.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

REST API design patterns provide a coherent set of rules to ensure APIs are predictable and easy to consume, reducing integration errors and speeding development.

Core Features & Use Cases

  • URL naming and resource structuring with pluralized, kebab-case paths
  • HTTP method semantics, status codes, and error payload conventions
  • Pagination, filtering, sorting, and search strategies for scalable APIs
  • API versioning and rate limiting guidelines for backward compatibility and reliability
  • Practical patterns for public and partner APIs, with examples and guardrails

Quick Start

Draft a new API contract following naming, method, error, pagination, filtering, and versioning guidelines, then implement and validate against these rules.

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 with consistent naming and error handling?

Design a REST API by applying pluralized, kebab-case resource paths, standard HTTP methods, typed error payloads, and consistent status codes to ensure predictable, interoperable endpoints that reduce integration errors.

What is the best way to handle pagination and filtering in a REST API?

Handle REST API pagination and filtering by applying scalable strategies for sorting and search. This ensures endpoints remain performant and predictable when serving large datasets across web services and partner integrations.

How does API versioning work for maintaining backward compatibility?

API versioning maintains backward compatibility by applying structured guidelines to endpoint evolution. This allows web services and partner integrations to update resources without breaking existing client implementations.

Can I use these REST API patterns for both internal and public endpoints?

Yes, these REST API design patterns apply to both public and internal endpoints across web services, mobile backends, and partner integrations, enforcing resource URL conventions and rate limiting guidelines for reliable consumption.

Why do I need standard HTTP status codes and typed error responses in my API?

Standard HTTP status codes and typed error responses are needed to improve interoperability and developer productivity. They enforce predictable semantics, allowing clients to handle errors systematically and reducing integration friction.

What are the limitations of relying on standard REST API design conventions?

Standard REST API design conventions require strict adherence to resource URL conventions and method semantics to function properly. Failing to apply consistent naming, pagination, and versioning guidelines can lead to integration errors and reduced scalability.