skills.rest
thc1006
thc1006COMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design-principles

Design REST and GraphQL APIs with principled patterns and templates.

20|3|Updated Jul 26, 2025
Search Tags:#design#documentation#validation#rest#graphql#patterns#apis
One-click install
npx skills add https://github.com/thc1006/nephoran-intent-operator --skill api-design-principles-thc1006
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/thc1006/nephoran-intent-operator/tree/main/.claude/skills/api-design-principles
Command: npx skills add https://github.com/thc1006/nephoran-intent-operator --skill api-design-principles-thc1006

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

REST and GraphQL API design is often inconsistent across teams, creating integration friction and maintenance challenges. This skill codifies principled patterns, guidelines, and best practices to design scalable, developer-friendly APIs.

Core Features & Use Cases

  • REST principles: resource-oriented design, standard HTTP methods, URL semantics, and versioning strategies.
  • GraphQL principles: schema-first design, clear resolver patterns, and efficient data loading.
  • Design patterns and best practices: pagination, error handling, input validation, and comprehensive documentation.
  • Use cases: creating new APIs, evaluating specifications, and establishing team-wide API design standards with reusable templates.
  • Real-world workflow: translate business requirements into a consistent API surface using REST and GraphQL patterns.

Quick Start

Design a complete REST and GraphQL API plan for a new service following the references and templates in the assets and references directories.

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 REST API resource design and HTTP semantics?▼

REST API resource design should follow resource-oriented patterns, standard HTTP methods, clear URL semantics, and consistent versioning strategies to ensure scalable and developer-friendly integration.

How do I design a GraphQL schema using schema-first principles?▼

GraphQL schema-first design involves defining clear resolver patterns, structuring queries and mutations explicitly, and optimizing data loading to establish efficient and maintainable API endpoints.

How do I handle pagination and error handling consistently across APIs?▼

API pagination and error handling require enforcing standardized design patterns and input validation guidelines, ensuring consistent integration experiences and reducing maintenance friction across development teams.

Can I use these API design patterns to establish team-wide standards?▼

Yes, you can establish team-wide API design standards by applying reusable reference templates and principled guidelines to evaluate specifications and architect new REST or GraphQL services.

REST vs GraphQL: which approach should I choose for my new API?▼

Choosing between REST and GraphQL depends on your integration needs: REST provides resource-oriented standard HTTP semantics, while GraphQL offers schema-first design with efficient data loading for complex queries.

Why does inconsistent API design create integration friction across teams?▼

Inconsistent API design creates integration friction because varying patterns for resource design, HTTP semantics, pagination, and error handling increase maintenance complexity and disrupt developer experience.

Related Skills

Explore More Software Engineering Skills→
Digit-HouseDigit-House

api-design

Guide REST and GraphQL API design with versioning, authentication, and OpenAPI documentation.

Official
Advanced
curiositechcuriositech
181

openapi-spec-writer

Generate OpenAPI 3.0/3.1 YAML or JSON specifications for REST APIs.

Official
Advanced
cin12211cin12211
218

rest-api-expert

Design REST APIs with resource models, versioning, error handling, and OpenAPI documentation.

Community
Basic
feasibleonefeasibleone
1

blong-rest

Implement REST APIs from OpenAPI specs within Blong's gateway.

Official
Intermediate