skills.rest
Thiago-Cruz-eng
Thiago-Cruz-engCOMMUNITY
Explore all skills by this author →
GitHub

api-design-principles

Apply REST and GraphQL design principles to API review checklists.

Updated Dec 20, 2023
Search Tags:#versioning#error handling#api design#rest#graphql#pagination#schema-first
One-click install
npx skills add https://github.com/Thiago-Cruz-eng/Hibrygame --skill api-design-principles-thiago-cruz-eng
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/Thiago-Cruz-eng/Hibrygame/tree/main/.claude/skills/api-design-principles
Command: npx skills add https://github.com/Thiago-Cruz-eng/Hibrygame --skill api-design-principles-thiago-cruz-eng

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill helps you avoid inconsistent, hard-to-use APIs by giving practical REST and GraphQL design principles, patterns, and review guidance that lead to scalable, maintainable interfaces.

Core Features & Use Cases

  • REST fundamentals: Resource-oriented routing, correct HTTP method semantics, pagination/filtering, and consistent status codes and error handling.
  • GraphQL fundamentals: Schema-first modeling, query/mutation structure, Relay-style pagination, and efficient resolver patterns.
  • Governance & standards: API versioning strategies and an implementation-focused checklist to support consistent team practices.
  • Use case: When you’re planning endpoints for a product, you can align REST/GraphQL choices, standardize error formats, and prevent common pitfalls like poor pagination and unclear resource design.

Quick Start

Draft a REST or GraphQL API specification using resource naming, HTTP method semantics, schema-first structure, and a consistent pagination and error-handling approach.

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

REST and GraphQL API design best practices require resource-oriented routing, correct HTTP semantics, schema-first modeling, and deterministic error handling to ensure maintainability and usability.

How do I standardize API error handling and status codes?▼

Standardize API error handling and status codes by applying deterministic error formats and correct HTTP method semantics across REST and GraphQL endpoints to prevent inconsistent interface behavior.

How do I implement pagination and filtering in GraphQL and REST APIs?▼

Implement pagination and filtering in GraphQL and REST APIs by applying documented pagination rules, such as Relay-style pagination for GraphQL, and consistent resource-oriented filtering strategies.

What are the most effective API versioning strategies?▼

Effective API versioning strategies provide governance and team standards by documenting versioning rules that prevent breaking changes and support consistent practices across REST and GraphQL services.

Should I use schema-first design for my GraphQL API?▼

Schema-first design for GraphQL APIs ensures consistent query and mutation structures by defining the schema before implementation, which improves resolver efficiency and overall API maintainability.

Related Skills

Explore More Software Engineering Skills→
HieubkavHieubkav

api-design-principles

Apply REST and GraphQL design principles to resolve API inconsistencies.

Community
Intermediate
hffmnnjhffmnnj
39

api-docs

Generate API reference documentation from OpenAPI specs and GraphQL schemas.

Community
Advanced
qprjack86qprjack86

azure-aigateway

Configure Azure API Management as an AI gateway for Azure OpenAI and MCP tools.

Community
Advanced
rodrigo-altissimorodrigo-altissimo

software-engineering-eng-api

Design complete REST, GraphQL, and gRPC API contracts with OpenAPI documentation.

Community
Advanced