skills.rest
nicolas-deyros
nicolas-deyrosCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

api-design-principles

Design REST and GraphQL APIs with structured design patterns.

Updated Jul 15, 2025
Search Tags:#versioning#documentation#rest#graphql#patterns#api-design
One-click install
npx skills add https://github.com/nicolas-deyros/astro-portfolio-v2 --skill api-design-principles-nicolas-deyros
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/nicolas-deyros/astro-portfolio-v2/tree/main/.agents/skills/api-design-principles
Command: npx skills add https://github.com/nicolas-deyros/astro-portfolio-v2 --skill api-design-principles-nicolas-deyros

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

API design often suffers from inconsistent patterns, confusing endpoints, and hard-to-use docs. This Skill provides a consolidated set of REST and GraphQL design principles to help teams craft scalable, maintainable, and developer-friendly APIs.

Core Features & Use Cases

  • REST Design Principles: resources first, proper HTTP methods, clear endpoints.
  • GraphQL Design Patterns: schema-first, resolvers, pagination, and error handling.
  • Versioning, pagination, error handling, and documentation best practices.
  • Use Case: designing a new microservice API, auditing an existing API, migrating REST to GraphQL, or standardizing API contracts across teams.

Quick Start

Draft your API contracts following the guidelines and run a design review against the internal API-design checklist.

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 REST and GraphQL APIs?▼

Core REST and GraphQL API design principles enforce resource orientation, correct HTTP semantics, schema-first design, and clear documentation to ensure scalable, maintainable, and developer-friendly contracts.

How do I standardize API contracts and design patterns across my team?▼

Standardize API contracts by applying structured design patterns and running design reviews against an internal checklist covering versioning, pagination, and error handling for both REST and GraphQL.

What is the best way to handle pagination and error handling in GraphQL APIs?▼

Handling pagination and error handling in GraphQL APIs follows schema-first design patterns using structured resolvers, enforcing clear resource boundaries and consistent error responses for maintainable endpoints.

Can I use these API design patterns to migrate an existing REST API to GraphQL?▼

Yes, these API design patterns support migrating between paradigms like REST to GraphQL by applying schema-first principles, proper HTTP semantics, and structured resolvers to refactor existing resources.

How do I audit an existing API specification for design consistency?▼

Audit an existing API specification by reviewing endpoints against principled design patterns, checking resource orientation, HTTP methods, versioning, and pagination to identify inconsistencies and improve maintainability.

Related Skills

Explore More Software Engineering Skills→
nahisahonahisaho
69

api-designer

Design RESTful, GraphQL, and gRPC APIs with OpenAPI and Protobuf definitions.

Community
Intermediate
icartshicartsh
4

api-designer

Design RESTful and GraphQL APIs with OpenAPI 3.0 specifications.

Community
Advanced
hpsgdhpsgd

api-design

Design RESTful API contracts with resource models, HTTP methods, and error handling.

Official
Advanced
gajjalaashok75-UIgajjalaashok75-UI
2

api-design-principles

Design REST and GraphQL APIs with resource-oriented conventions and schema patterns.

Community
Advanced