skills.rest
jh941213
jh941213COMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design-principles

Guide REST and GraphQL API design with schema-first patterns and templates.

125|35|Updated Jan 21, 2026
Search Tags:#design#documentation#API#GraphQL#REST#patterns#best-practices
One-click install
npx skills add https://github.com/jh941213/my-claude-code-asset --skill api-design-principles-jh941213
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/jh941213/my-claude-code-asset/tree/main/skills/api-design-principles
Command: npx skills add https://github.com/jh941213/my-claude-code-asset --skill api-design-principles-jh941213

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This skill provides comprehensive guidance for designing REST and GraphQL APIs, helping teams create intuitive, scalable, and maintainable interfaces.

Core Features & Use Cases

  • REST-first guidance: resource-oriented URLs, correct HTTP methods, and consistent status handling to ensure predictable APIs.
  • GraphQL-first design: schema-first approach with strong typing, clear relationships, and efficient query patterns.
  • Cross-cutting patterns: pagination, versioning, error payloads, input validation, and data loading strategies to support robust, developer-friendly APIs.
  • Use Case: When starting a new API project, use this skill to establish design standards, review specifications, and standardize documentation.

Quick Start

Define your API resources (for example, users and orders) and draft REST endpoints with proper HTTP methods and status codes. Then design a GraphQL schema with types, queries, mutations, and pagination; compare both approaches against the guidelines and templates in the references. Finally, adapt the templates to your tech stack and generate a consistent OpenAPI/GraphQL contract.

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 design regarding resources and HTTP status codes?▼

REST API design best practices involve using resource-oriented URLs, correct HTTP methods, and consistent status handling to ensure predictable interfaces. This skill provides recipe-style principles and annotated examples to enforce these standards across typical projects.

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

To design a GraphQL schema, define types, queries, mutations, and pagination using a schema-first approach with strong typing. This skill provides guidance on clear relationships, efficient query patterns, and DataLoader strategies to support robust implementations.

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

Handle pagination, versioning, and errors by applying cross-cutting patterns for consistent payloads and input validation. This skill offers ready-to-use templates and recipe-style principles to standardize these data loading strategies across REST and GraphQL APIs.

Should I choose REST or GraphQL for my new API project?▼

Choosing between REST and GraphQL depends on your data fetching needs; REST uses resource-oriented endpoints, while GraphQL offers strong typing and efficient queries. This skill helps you compare both approaches against established guidelines to decide.

How do I generate OpenAPI and GraphQL contracts from API design templates?▼

Generate OpenAPI and GraphQL contracts by adapting the provided templates to your tech stack after defining resources and endpoints. This skill includes ready-to-use templates and references to help you standardize documentation and create consistent contracts.

Related Skills

Explore More Software Engineering Skills→
reactivereactive
2.0k

rdc-rest

Define type-safe REST APIs with schema-driven normalization and caching.

Official
Advanced
michsindlingermichsindlinger
1

api-documentation

Generate OpenAPI and Swagger documentation for REST and GraphQL APIs.

Community
Advanced
microwindmicrowind
65

GraphQL API开发

Design GraphQL schemas, resolvers, and DataLoader strategies with security controls.

Official
Advanced
ChegginCheggin
1

documentation-generator

Generate API references, user guides, and changelogs from code and git history.

Community
Advanced