api-design-principles

Design, develop, and optimize REST and GraphQL APIs with schema-first patterns.

13|Updated Feb 4, 2026

Search Tags:#versioning #design patterns #api design #rest #graphql #data-loader

Ready to run

npx skills add https://github.com/abeldotam/bmad-viewer --skill api-design-principles-abeldotam

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/abeldotam/bmad-viewer/tree/main/.agents/skills/api-design-principles
Command: npx skills add https://github.com/abeldotam/bmad-viewer --skill api-design-principles-abeldotam

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires fastapi, pydantic, uvicorn, and includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

This collection of REST and GraphQL API design principles helps teams build intuitive, scalable, and maintainable APIs from the ground up, reducing ambiguity and rework.

Core Features & Use Cases

Schema-first design: Start with a strongly-typed API schema to guide implementation and foster consistency across REST and GraphQL APIs.
N+1 prevention: Use data loaders and batching to avoid inefficient data access patterns.
Pagination, versioning, and error handling: Standardized patterns for reliable, evolvable APIs with clear client contracts.
Practical patterns: REST endpoints, GraphQL schemas, and mutation/payload strategies documented for teams to reuse.
Use cases include designing new APIs, reviewing existing specs, and establishing API standards for a team.

Quick Start

Analyze your current API design and begin applying REST/GraphQL patterns to improve usability and consistency.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema

What is schema-first design and how does it improve REST and GraphQL API usability?▼

Schema-first design uses a strongly-typed API schema to guide implementation, fostering consistency across REST and GraphQL APIs. This approach reduces ambiguity and rework by establishing clear client contracts before development begins.

How do I prevent N+1 query problems in GraphQL APIs?▼

To prevent N+1 query problems in GraphQL APIs, apply data loaders and batching patterns. This technique groups multiple individual data requests into a single batched query, avoiding inefficient data access patterns.

What is the best way to implement API versioning and error handling for production environments?▼

The best way to implement API versioning and error handling is to apply standardized patterns for reliable, evolvable APIs. Use consistent error handling and clear versioning strategies to maintain client contracts across production environments.

Does this approach work with FastAPI and Pydantic for REST endpoint development?▼

Yes, this approach works with FastAPI and Pydantic for REST endpoint development. You can apply these API design principles and practical patterns to FastAPI projects to enforce schema-first design and consistent error handling.

How do I establish API standards for a team reviewing existing REST and GraphQL specs?▼

Establish API standards for a team by applying documented practical patterns for REST endpoints, GraphQL schemas, and mutation strategies. Review existing specs against these principles to improve usability, performance, and maintainability.