skills.rest
futuregerald
futuregeraldCOMMUNITY
Explore all skills by this author →
𝕏@futuregeraldGitHub

api-design-principles

Guide REST and GraphQL API design with versioning and error-handling patterns.

6|Updated Feb 4, 2026
Search Tags:#design#versioning#documentation#api#rest#graphql#patterns
One-click install
npx skills add https://github.com/futuregerald/futuregerald-claude-plugin --skill api-design-principles-futuregerald
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/futuregerald/futuregerald-claude-plugin/tree/main/skills/api-design-principles
Command: npx skills add https://github.com/futuregerald/futuregerald-claude-plugin --skill api-design-principles-futuregerald

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

Provide design guidance for building scalable REST and GraphQL APIs.

Core Features & Use Cases

  • REST design principles: resource-oriented design, HTTP method semantics, and consistent naming.
  • GraphQL design: schema-first development, queries, mutations, subscriptions, and introspection.
  • Versioning, error handling, pagination, HATEOAS, and DataLoader guidance; common pitfalls and practical resources.

Quick Start

Draft a complete REST/GraphQL API design blueprint for a new service following these 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 scalable REST and GraphQL APIs?▼

Versioning strategies for REST APIs include URI path versioning and header versioning to manage breaking changes without disrupting existing clients. The guidance provides patterns for implementing effective versioning across your service contracts.

How do I handle pagination and error handling patterns in GraphQL schemas?▼

GraphQL pagination patterns utilize cursor-based connections for traversing large result sets, while error handling uses structured response formats. The guidance covers these patterns alongside DataLoader implementation for batching requests.

What is the best way to draft a complete API design blueprint for a new service?▼

Drafting a complete API design blueprint involves applying resource-oriented REST principles and schema-first GraphQL patterns to define interface contracts. This approach ensures consistent naming, pagination, and error handling standards across the new service.

Does this API design guidance cover HATEOAS and DataLoader implementation?▼

Yes, the API design guidance covers HATEOAS for REST hypermedia constraints and DataLoader implementation for GraphQL request batching. These patterns are included to optimize data fetching and maintain scalable interface contracts.

When should I choose REST resource design over GraphQL schema-first development?▼

Choose REST resource design for standardized HTTP method semantics and cached endpoints, or GraphQL schema-first development for flexible client-driven queries. The guidance helps review interface contracts to determine the appropriate pattern for your use case.

Related Skills

Explore More Software Engineering Skills→
chidekinachidekina
2

api-design-principles

Define and enforce scalable REST and GraphQL API design patterns.

Community
Advanced
zhangzhang-111-izhangzhang-111-i
2

mcp-server-builder

Generate MCP server scaffolds and tool manifests from OpenAPI specifications.

Community
Advanced
fgarofalo56fgarofalo56
6

azure-api-management

Manage APIs with Azure API Management using Azure CLI and Bicep.

Community
Advanced
bytetalentbytetalent

TypeScript Strict Mode

Enforce TypeScript strict mode across Next.js and Expo code generation.

Official
Intermediate