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.

About

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

Advanced GraphQL schema design patterns including N+1 query prevention and complexity limiting.
12 GitHub stars
Protocol selection logic for choosing between REST, GraphQL, and gRPC based on performance and compatibility.
Detailed gRPC service definition patterns and standard error handling implementations.
Standardized RESTful resource naming and HTTP status code mapping for consistent developer experiences.
Best practices for implementing efficient pagination, filtering, and sorting mechanisms.

Use Cases

Evaluating architectural trade-offs when initiating a new microservice or public-facing API.
Refactoring inconsistent API endpoints to adhere to industry-standard naming and behavior conventions.
Designing evolution-friendly schemas that support long-term backward compatibility and deprecation.

About

Key Features

Advanced GraphQL schema design patterns including N+1 query prevention and complexity limiting.
12 GitHub stars
Protocol selection logic for choosing between REST, GraphQL, and gRPC based on performance and compatibility.
Detailed gRPC service definition patterns and standard error handling implementations.
Standardized RESTful resource naming and HTTP status code mapping for consistent developer experiences.
Best practices for implementing efficient pagination, filtering, and sorting mechanisms.

Use Cases

Evaluating architectural trade-offs when initiating a new microservice or public-facing API.
Refactoring inconsistent API endpoints to adhere to industry-standard naming and behavior conventions.
Designing evolution-friendly schemas that support long-term backward compatibility and deprecation.