skills.rest
msadowskigraduate
msadowskigraduateCOMMUNITY
Explore all skills by this author →
GitHub

api-design-principles

Design scalable REST and GraphQL APIs with versioning, pagination, and error handling.

Updated Aug 23, 2026
Search Tags:#design#versioning#api#rest#graphql#pagination
One-click install
npx skills add https://github.com/msadowskigraduate/crusader --skill api-design-principles-msadowskigraduate
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/msadowskigraduate/crusader/tree/main/.agents/skills/api-design-principles
Command: npx skills add https://github.com/msadowskigraduate/crusader --skill api-design-principles-msadowskigraduate

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

Guides teams to design scalable, maintainable REST and GraphQL APIs by applying proven design principles and best practices to real-world projects.

Core Features & Use Cases

  • Resource-oriented REST design with consistent naming, versioning strategies, pagination, and robust error handling.
  • GraphQL schema-first approach with clear type definitions, efficient data fetching, and well-structured mutation patterns.
  • Use cases include designing new APIs, auditing existing specifications, and governing API standards across teams and projects.

Quick Start

Design an initial API contract by listing resources, selecting a versioning approach, and sketching REST endpoints or a GraphQL schema to apply immediately.

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?▼

Scalable REST and GraphQL API design relies on resource-oriented naming, consistent error formats, clear versioning strategies, and performance-conscious patterns like data batching and DataLoader to ensure maintainability.

How do I apply a schema-first approach to GraphQL API design?▼

Applying a GraphQL schema-first approach involves defining clear type definitions, structuring efficient mutation patterns, and utilizing data batching to optimize data fetching operations for clients.

What is the best way to implement versioning and pagination for REST APIs?▼

The best way to implement REST API versioning and pagination is by codifying proven design principles that enforce resource-oriented structures, consistent naming conventions, and standardized data retrieval boundaries.

Can I audit existing API specifications for governance and consistency?▼

Yes, you can audit existing API specifications to enforce governance across teams by reviewing REST and GraphQL endpoints for consistent error handling, security standards, and proper versioning strategies.

REST vs GraphQL: which approach should I choose for greenfield API projects?▼

For greenfield API projects, choosing REST provides resource-oriented design with robust pagination, while GraphQL offers a schema-first approach with efficient data fetching and DataLoader for batched requests.

Why does my GraphQL API suffer from performance issues during data fetching?▼

GraphQL API performance issues during data fetching often occur when lacking performance-conscious patterns; applying DataLoader and data batching mitigates these bottlenecks by efficiently grouping multiple requests.

Related Skills

Explore More Software Engineering Skills→
VeradelaCruzVeradelaCruz

api-design

Define API requirements and generate OpenAPI or GraphQL schemas.

Community
Intermediate
agigante80agigante80

api-design-principles

Plan and execute scalable REST and GraphQL API designs with established principles.

Community
Advanced
minhquan2904minhquan2904

api-patterns

Identify and standardize REST API design patterns for consistent API contracts.

Community
Advanced
ynittoynitto
1

api-designer

Design REST or GraphQL APIs with automated OpenAPI and GraphQL schema generation.

Community
Advanced