skills.rest
amurata
amurataCOMMUNITY
Explore all skills by this author →
GitHub

api-design-principles

Guide RESTful and GraphQL API design with principles, patterns, and best practices.

6|2|Updated Oct 19, 2025
Search Tags:#schema design#api design#rest#developer experience#graphql#api best practices
One-click install
npx skills add https://github.com/amurata/cc-tools --skill api-design-principles-amurata
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/amurata/cc-tools/tree/main/plugins/backend-development/skills/api-design-principles
Command: npx skills add https://github.com/amurata/cc-tools --skill api-design-principles-amurata

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill helps developers design, review, and improve RESTful and GraphQL APIs, ensuring they are intuitive, scalable, and maintainable.

Core Features & Use Cases

  • RESTful Principles: Understand resource-oriented design, HTTP methods, and status codes.
  • GraphQL Principles: Master schema design, query structure, and mutation patterns.
  • Best Practices: Learn about versioning, pagination, error handling, and N+1 problem prevention.
  • Use Case: When designing a new microservice API, use this Skill to ensure adherence to best practices for both REST and GraphQL endpoints, leading to a more developer-friendly experience.

Quick Start

Review the provided checklist to ensure the new user API adheres to RESTful design principles.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema
What are the best practices for RESTful API resource-oriented design?▼

GraphQL schema design principles focus on structuring types, queries, and mutations effectively. This prevents common pitfalls like the N+1 problem and ensures a maintainable, developer-friendly API.

How do I handle API versioning, pagination, and error handling?▼

API design principles dictate implementing structured versioning, pagination, and standardized error handling. Following these patterns improves developer experience and maintains API consistency across updates.

How do I design a scalable microservice API for both REST and GraphQL?▼

Designing a scalable microservice API requires applying core principles for both REST and GraphQL endpoints. Using a design checklist ensures adherence to best practices, resulting in a better developer experience.

When should I choose GraphQL over REST for my API design?▼

Choosing GraphQL over REST depends on your data fetching needs. GraphQL principles offer flexible query structures and mutation patterns, whereas RESTful principles provide standardized resource-oriented endpoints.

How do I prevent the N+1 problem in GraphQL API development?▼

Preventing the N+1 problem in GraphQL API development requires applying specific schema design patterns and best practices. This optimizes query execution and maintains scalable API performance.

Related Skills

Explore More Software Engineering Skills→
takemo101takemo101

basic-design-writer

Generate foundational system design documents in Japanese with Mermaid diagrams.

Community
Intermediate
Dokkabei97Dokkabei97
2

api-first-design

Design API contracts with OpenAPI and GraphQL schemas.

Community
Intermediate
weirdgmeweirdgme
4

api-engineering

Automate API design and governance with REST, GraphQL, and gRPC best practices.

Community
Advanced
vinhgiangvinhgiang

nx-generate

Generate code artifacts in an Nx monorepo using Nx generators.

Community
Intermediate