api-design

Provide REST and GraphQL API design guidelines covering versioning, logging, and observability.

2|Updated Dec 2, 2025
One-click install
npx skills add https://github.com/kcenon/claude-config --skill api-design-kcenon
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/kcenon/claude-config/tree/main/plugin/skills/api-design
Command: npx skills add https://github.com/kcenon/claude-config --skill api-design-kcenon

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill provides guidelines for designing RESTful and GraphQL APIs, including versioning, consistent responses, observability, logging, and rate limiting.

Core Features & Use Cases

  • RESTful conventions: Proper resource naming, HTTP methods, and status codes.
  • Versioning & Compartments: Clear API versioning strategy to maintain backward compatibility.
  • Observability: Structured logging, metrics, and traces to monitor APIs.

Quick Start

Design a REST endpoint: GET /api/v1/users to list users with pagination and proper status codes.

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 that follow best practices for versioning and scalability?

REST API design requires clear versioning strategies, proper resource naming, and correct HTTP methods and status codes. This Skill provides comprehensive guidelines for RESTful conventions, versioning approaches to maintain backward compatibility, and consistent response formatting across endpoints to ensure APIs scale reliably.

What's the difference between REST and GraphQL API design, and when should I use each?

REST uses HTTP methods on resource endpoints; GraphQL uses a single endpoint with flexible query syntax. This Skill covers both approaches, helping you understand RESTful conventions for traditional APIs and GraphQL design patterns, so you can choose based on your client needs and data structure.

How do I add observability and logging to my APIs?

API observability combines structured logging, metrics, and traces to monitor runtime behavior. This Skill guides you through implementing structured logging and observability practices, enabling you to track API performance, diagnose issues, and maintain visibility across distributed systems.

What are the key principles for consistent API error handling and responses?

Consistent error handling ensures clients can parse failures predictably. This Skill provides guidelines for standardized error responses, proper HTTP status codes, and SOLID principles applied to API design, so all endpoints behave predictably across your service.

How do I implement rate limiting and versioning strategies for growing APIs?

Rate limiting protects APIs from overload; versioning maintains backward compatibility as you evolve. This Skill covers versioning compartments and rate limiting strategies to help you scale APIs safely while supporting multiple client versions.

Can I use these REST and GraphQL guidelines for microservices architectures?

Yes. This Skill applies to microservices implementation, covering RESTful and GraphQL design patterns, versioning, observability, and consistent responses—all essential for coordinating independent services and managing API contracts across distributed teams.