When should I choose REST over GraphQL?

REST is generally preferred for public APIs where broad client compatibility and standard HTTP caching are required, whereas GraphQL excels in mobile apps with complex data requirements to prevent over-fetching.

Does this skill provide guidance on API pagination?

Yes, the skill covers both offset-based and cursor-based pagination, recommending cursors for high-performance, large-scale datasets to ensure stability.

Can I use this for internal microservices?

Absolutely. It includes specific sections on gRPC, which is the recommended protocol for high-performance, polyglot internal microservice communication.

How does the skill handle API versioning?

It provides a framework for API evolution, including rules for backward-compatible changes, strategies for deprecation, and guidelines for managing breaking changes.

API Design Fundamentals

Name: API Design Fundamentals
Author: melodic-software

bymelodic-software

•

API Development

Guides the design of robust, scalable APIs by providing architectural best practices for REST, GraphQL, and gRPC implementations.

API Design Fundamentals is a specialized skill for Claude Code that assists developers and architects in making critical structural decisions for their web services. It offers a comprehensive framework for selecting the appropriate protocol—comparing REST, GraphQL, and gRPC—based on specific use cases such as public APIs, mobile apps, or microservices. Beyond protocol selection, the skill provides actionable guidance on resource modeling, naming conventions, pagination strategies, and backward compatibility, ensuring that APIs are intuitive for developers and resilient over time.

Key Features

01Advanced GraphQL schema design patterns including N+1 query prevention and complexity limiting.

0212 GitHub stars

03Protocol selection logic for choosing between REST, GraphQL, and gRPC based on performance and compatibility.

04Detailed gRPC service definition patterns and standard error handling implementations.

05Standardized RESTful resource naming and HTTP status code mapping for consistent developer experiences.

06Best practices for implementing efficient pagination, filtering, and sorting mechanisms.

Use Cases

01Evaluating architectural trade-offs when initiating a new microservice or public-facing API.

02Refactoring inconsistent API endpoints to adhere to industry-standard naming and behavior conventions.

03Designing evolution-friendly schemas that support long-term backward compatibility and deprecation.

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add melodic-software/claude-code-plugins api-design-fundamentals

For use in Claude.ai and ChatGPT

Download Skill