skills.rest
sandeshbagmare
sandeshbagmareCOMMUNITY
Explore all skills by this author →
GitHub

api-design-principles

Explain REST and GraphQL API design principles, including resource-oriented architecture and schema-first development.

Updated May 30, 2026
Search Tags:#api design#rest#graphql#api architecture#restful design
One-click install
npx skills add https://github.com/sandeshbagmare/AgenticQ --skill api-design-principles-sandeshbagmare
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/sandeshbagmare/AgenticQ/tree/main/examples/python_agenticq_demo/.claude/plugins/backend-development/skills/api-design-principles
Command: npx skills add https://github.com/sandeshbagmare/AgenticQ --skill api-design-principles-sandeshbagmare

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill helps you master REST and GraphQL API design principles, ensuring your APIs are intuitive, scalable, and maintainable.

Core Features & Use Cases

  • RESTful Design Principles: Learn about resource-oriented architecture, HTTP methods, and status codes.
  • GraphQL Design Principles: Understand schema-first development, query structure, and API versioning strategies.
  • Best Practices: Follow guidelines for consistent naming, statelessness, and error handling.
  • Common Pitfalls: Avoid over-fetching, under-fetching, breaking changes, and other common mistakes.
  • Use Case: Use this Skill to design a new REST or GraphQL API, refactor an existing one, or establish API design standards for your team.

Quick Start

To start, review the provided documentation on REST and GraphQL API 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 core principles for designing a scalable REST API?▼

Core REST API design principles include resource-oriented architecture, proper use of HTTP methods, standard status codes, statelessness, and consistent naming to ensure your API is intuitive and maintainable.

How do I start designing a GraphQL API using schema-first development?▼

GraphQL API design uses schema-first development to define your data structure and query patterns upfront, ensuring strict type safety, controlled data fetching, and effective API versioning strategies.

What is the best way to avoid over-fetching and under-fetching in API architecture?▼

To avoid over-fetching and under-fetching in API architecture, apply GraphQL for precise query structures or follow REST best practices to ensure endpoints return exactly the required resource data.

How should I handle errors and breaking changes in RESTful and GraphQL APIs?▼

Handle errors and breaking changes in RESTful and GraphQL APIs by implementing consistent error handling guidelines and establishing clear API versioning strategies to prevent breaking existing clients.

Can I use these API design principles to refactor an existing API?▼

Yes, you can use these API design principles to refactor an existing REST or GraphQL API by applying resource-oriented architecture, consistent naming, and statelessness to improve maintainability.

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

Choose GraphQL over REST for your API architecture when you need schema-first development and precise query structures to prevent over-fetching, whereas REST suits standard resource-oriented architecture.

Related Skills

Explore More Software Engineering Skills→
HechaoYannetHechaoYannet

create-architecture

Generate a master architecture document from GDDs, ADRs, and governance constraints.

Community
Advanced
icartshicartsh
4

api-designer

Design RESTful and GraphQL APIs with OpenAPI 3.0 specifications.

Community
Advanced
simon-downessimon-downes
1

policy-lang-python

Enforce Python coding standards with Black, Ruff, pytest, and pyproject.toml.

Community
Advanced
Next-ofkinNext-ofkin
1

backend-architect

Design scalable backend architectures for APIs and microservices.

Community
Advanced