api-design-principles

Guide REST and GraphQL API design with best practices and common pitfalls.

Updated Jun 16, 2026

Search Tags:#schema design #api design #rest #graphql #restful design

Ready to run

npx skills add https://github.com/breakingcircuits1337/agent-skills --skill api-design-principles-breakingcircuits1337

💬 Prompt for ChatGPT / Claude Chat▼

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

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve?

This Skill unit provides a comprehensive guide to API design principles, helping users understand and apply best practices for REST and GraphQL APIs.

Core Features & Use Cases

REST API Design: Learn about RESTful design principles, including resource-oriented architecture, HTTP methods semantics, and versioning strategies.
GraphQL API Design: Understand GraphQL schema design, resolver patterns, and data loading techniques.
Best Practices: Explore best practices for REST and GraphQL APIs, including naming conventions, stateless design, error handling, and documentation.
Common Pitfalls: Identify common pitfalls in API design, such as over-fetching/under-fetching, breaking changes, and inconsistent error formats.
Resources: Access detailed guides, templates, and checklists for REST and GraphQL API design.

Quick Start

To get started, read the 'API Design Principles' guide to understand the core concepts and best practices for designing APIs.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema

What are the core principles of RESTful API design?▼

RESTful API design principles focus on resource-oriented architecture, correct HTTP methods semantics, stateless design, and versioning strategies to ensure scalable and consistent interfaces.

How do I design a GraphQL schema and handle data loading?▼

GraphQL schema design involves defining types and resolver patterns, while data loading techniques optimize batch fetching to prevent waterfall requests and improve query performance.

What is the best way to handle errors and naming conventions in APIs?▼

Best practices for API error handling and naming conventions involve maintaining consistent error formats and predictable resource naming to avoid breaking changes and improve usability.

How do I avoid over-fetching and under-fetching in API design?▼

To avoid over-fetching and under-fetching, apply GraphQL schema design for precise client-specified queries or follow REST principles to structure resources efficiently and minimize payload bloat.

REST vs GraphQL: how do I choose the right API architecture?▼

Choosing between REST and GraphQL depends on your needs: REST provides standard resource-oriented endpoints, while GraphQL offers flexible resolver patterns and schema design to prevent data fetching issues.

When should I version my REST API and what pitfalls should I avoid?▼

Version your REST API when making breaking changes to endpoints, and avoid common pitfalls like inconsistent error formats or violating stateless design principles during the update process.