skills.rest
carlopezzuto
carlopezzutoCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design-principles

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

3|1|Updated Nov 5, 2025
Search Tags:#versioning#rest#graphql#best-practices#pagination#api-design#data-loader
One-click install
npx skills add https://github.com/carlopezzuto/agents --skill api-design-principles-carlopezzuto
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/carlopezzuto/agents/tree/main/.claude/skills/api-design-principles
Command: npx skills add https://github.com/carlopezzuto/agents --skill api-design-principles-carlopezzuto

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

Designing APIs consistently across REST and GraphQL is challenging without a shared design system. This skill provides a comprehensive set of principles and patterns to guide API design, versioning, pagination, error handling, and documentation, reducing ambiguity and accelerating delivery.

Core Features & Use Cases

  • RESTful design principles: resource-oriented endpoints, correct HTTP semantics, and predictable naming.
  • GraphQL design principles: schema-first development, typed schemas, queries, mutations, and subscriptions.
  • Versioning and evolution: strategies for URL, header, and query-based versioning; deprecation and migration practices.
  • Pagination and filtering: patterns for efficient data access, including cursor-based and offset-based approaches.
  • Error handling and observability: structured error payloads, consistent status codes, and monitoring hooks.
  • Practical templates and references: ready-to-use templates and example references to accelerate adoption.

Quick Start

Apply REST and GraphQL design principles to your upcoming API project.

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 and GraphQL API pagination and error handling?▼

REST and GraphQL API design best practices include adopting cursor-based pagination for efficient data access and utilizing structured error payloads with consistent status codes. This standardizes data retrieval and observability across both paradigms.

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

To design a GraphQL schema using a schema-first approach, define typed schemas, queries, mutations, and subscriptions before implementation. This method enforces strict contract definitions and standardizes patterns for efficient API development.

What are the strategies for API versioning and evolution in REST and GraphQL?▼

API versioning and evolution strategies include URL, header, and query-based versioning for REST, alongside structured deprecation and migration practices. These approaches manage breaking changes while maintaining backward compatibility across ecosystems.

When should I use DataLoader in GraphQL API design?▼

Use DataLoader in GraphQL API design to batch and cache database requests, preventing the N+1 query problem during complex nested queries. It provides specific guidance for optimizing data fetching efficiency within your schema.

How do I migrate an API between REST and GraphQL paradigms?▼

Migrating an API between REST and GraphQL paradigms involves applying standardized design principles, mapping resource-oriented endpoints to typed schemas, and structuring evolution practices to transition workflows without breaking existing clients.

Related Skills

Explore More Software Engineering Skills→
markky21markky21

api-design-principles

Apply REST and GraphQL principles to design consistent API interfaces.

Community
Basic
icartshicartsh
4

api-designer

Design RESTful and GraphQL APIs with OpenAPI 3.0 specifications.

Community
Advanced
wpankwpank
11

api-design-principles

Provides RESTful and GraphQL API design principles including resource modeling, HTTP semantics, pagination, error handling, versioning, schema design, REST vs GraphQL decision frameworks, FastAPI examples, and pre-implementation checklists.

Community
Intermediate
passionseedpassionseed
2

ai-gateway

Route LLM API calls through a unified TrueFoundry AI Gateway.

Official
Advanced