skills.rest
fanguyun
fanguyunCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design-principles

Provides guidance on REST and GraphQL API design principles and patterns.

Updated May 31, 2026
Search Tags:#api design#rest#graphql#api patterns#api best practices#api principles
One-click install
npx skills add https://github.com/fanguyun/SkillManager --skill api-design-principles-fanguyun
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/fanguyun/SkillManager/tree/main/api-design-principles
Command: npx skills add https://github.com/fanguyun/SkillManager --skill api-design-principles-fanguyun

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill unit addresses the challenge of designing intuitive, scalable, and maintainable APIs. It provides guidance on REST and GraphQL API design principles, aiding in the creation of APIs that delight developers and stand the test of time.

Core Features & Use Cases

  • API Design Principles: Offers comprehensive principles for REST and GraphQL API design.
  • When to Use: Ideal for designing new APIs, reviewing specifications, establishing standards, and migrating between paradigms.
  • Core Concepts: Covers RESTful design principles, GraphQL design principles, and API versioning strategies.
  • REST API Design Patterns: Provides examples and best practices for common REST API patterns.
  • GraphQL Design Patterns: Offers guidance on schema design, resolver design, pagination, mutations, and subscriptions.
  • Best Practices: Includes best practices for REST and GraphQL APIs, such as consistent naming, statelessness, error handling, and documentation.
  • Common Pitfalls: Warns against common pitfalls in API design, such as over-fetching/under-fetching, breaking changes, and poor documentation.

Quick Start

Run the 'api-design-principles' skill to access the complete guide on API design principles and patterns.

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 REST and GraphQL API design?▼

Core API design principles cover consistent naming, statelessness, schema design, and error handling for both REST and GraphQL APIs. They guide developers in creating intuitive, scalable, and maintainable interfaces that stand the test of time.

REST vs GraphQL: which API design pattern should I choose?▼

REST design patterns suit resource-based architectures, while GraphQL design patterns excel at resolving over-fetching and under-fetching issues. Choosing between them depends on your data fetching complexity and client flexibility requirements.

How do I design a GraphQL schema with pagination and mutations?▼

GraphQL schema design involves defining types, queries, mutations, and subscriptions. Effective design patterns include specific resolver designs and pagination strategies to ensure efficient data retrieval and modification.

What are common pitfalls in API versioning and error handling?▼

Common API design pitfalls include introducing breaking changes, poor documentation, and improper error handling. Establishing clear API versioning strategies and consistent error responses helps avoid these architectural traps.

How do I establish API standards and review specifications for new APIs?▼

Establishing API standards involves applying best practices for consistent naming, statelessness, and documentation to your specifications. Reviewing designs against these comprehensive principles ensures new APIs delight developers.

Related Skills

Explore More Software Engineering Skills→
jinwoonghongjinwoonghong

moai-domain-backend

Design REST or GraphQL APIs with authentication and database integration.

Community
Advanced
belokonmbelokonm
8

api-designer

Design REST and GraphQL APIs and generate OpenAPI 3.1 specifications.

Community
Advanced
tranhieutttranhieutt
70

api-design

Review REST and GraphQL API contracts for naming, schema, auth, and versioning issues.

Community
Intermediate
ajianazajianaz
4

api-builder

Design and implement REST, GraphQL, gRPC, and WebSocket APIs.

Community
Advanced