api-design

Design REST API patterns for pagination, filtering, versioning, and error handling.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Designing REST APIs with consistent, scalable patterns is challenging; this skill consolidates best practices to ensure predictable contracts, robust behavior, and maintainable implementations across teams.

Core Features & Use Cases

  • Resource naming conventions ( nouns, plural, kebab-case )
  • HTTP methods and status codes mapping (GET/POST/PUT/PATCH/DELETE with semantic responses)
  • Pagination, filtering, and sorting strategies (cursor and offset options)
  • Versioning and deprecation guidance for public/private APIs
  • Error handling formats and structured responses for client clarity
  • Authentication and authorization patterns for protected endpoints

Quick Start

Follow these patterns when designing a new API: map resources to endpoints, implement proper status codes, and enable pagination and filtering.

Frequently Asked Questions about api-design

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

FAQPage Schema
How do I design REST APIs with consistent pagination and filtering?

To design REST APIs with consistent pagination and filtering, apply standardized patterns like cursor or offset options for pagination, map resources to plural nouns, and implement structured response formats for client clarity.

What are the best practices for REST API versioning and deprecation?

Best practices for REST API versioning and deprecation involve applying standardized guidance for public and private APIs, ensuring predictable contracts, and maintaining documentation alignment to support evolving endpoints without breaking clients.

How should I structure error handling formats for developer-friendly REST APIs?

Error handling formats for developer-friendly REST APIs should use structured responses that provide client clarity, mapping HTTP status codes to semantic responses and enforcing standards across platforms for robust behavior.

When do I need authentication and rate limiting patterns for protected endpoints?

You need authentication and rate limiting patterns for protected endpoints when designing robust REST APIs that require secure access control, enforcing authorization standards and preventing abuse across evolving API contracts.

What HTTP methods and status codes should I map for new REST API endpoints?

Map HTTP methods like GET, POST, PUT, PATCH, and DELETE to semantic status code responses for new REST API endpoints. This ensures consistent behavior, predictable contracts, and maintainable implementations across platforms.

Does this REST API design approach work for contract reviews and evolving APIs?

Yes, this REST API design approach works for contract reviews and evolving APIs by enforcing standards for resource naming, HTTP methods, response formats, and documentation alignment, ensuring scalable and consistent patterns across teams.