skills.rest
Maykesantos98
Maykesantos98COMMUNITY
Explore all skills by this author →
GitHub

api-design-principles

Design REST and GraphQL APIs with resource-oriented routing and schema-first modeling.

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

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill helps you avoid brittle, hard-to-use API designs by applying proven REST and GraphQL conventions, consistent pagination, predictable error handling, and maintainable versioning strategies.

Core Features & Use Cases

  • REST resource design patterns (collections, nested resources, correct HTTP method semantics) to keep endpoints intuitive and consistent.
  • GraphQL schema-first patterns (types, queries, mutations, pagination, inputs/payloads) to ensure a clear contract between clients and servers.
  • Operational guidance for quality including consistent error structures, status codes, pagination best practices, and API design checklists for reviews and standards-setting.
  • Use Case: You are about to create a new backend for a product dashboard and need endpoints that support pagination, filtering, and developer-friendly documentation while remaining evolution-ready.

Quick Start

Ask the AI to review your proposed REST endpoints and GraphQL schema against REST/GraphQL best practices, including pagination, versioning, and standardized error responses.

Frequently Asked Questions about api-design-principles

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What is the best way to design REST API endpoints for pagination and filtering?▼

REST API design applies resource-oriented routing and HTTP semantics to keep endpoints intuitive. It enforces consistent pagination patterns and filtering conventions to ensure collections remain scalable and developer-friendly.

How do I standardize error handling and status codes in GraphQL and REST APIs?▼

Standardizing error handling involves defining consistent error structures and HTTP status-code behavior across REST and GraphQL. This ensures predictable API responses during mutation payload design and routine CRUD operations.

How do I choose a versioning strategy when refactoring an API?▼

Choosing a versioning strategy requires defining rules for API evolution during refactoring or migrations. It maintains backward compatibility while applying resource-oriented routing and schema-first modeling standards.

Can I use this approach to migrate a REST API to GraphQL?▼

Yes, this approach supports migrations between REST and GraphQL for common backend workflows. It translates CRUD operations and mutation payload designs into GraphQL constructs while standardizing pagination and error behavior.

When should I not use GraphQL over REST for my backend API?▼

You should reconsider GraphQL over REST when facing complex N+1 data fetching patterns that cannot be easily resolved. REST resource design may offer simpler HTTP semantics for basic CRUD workflows without schema overhead.

Related Skills

Explore More Software Engineering Skills→
diShine-digital-agencydiShine-digital-agency
1

shine-api-design

Generate OpenAPI 3.1 skeletons or GraphQL SDL for a given domain.

Community
Intermediate
dinoudondinoudon

api-documentation

Generates API references and SDK scaffolds from OpenAPI specifications.

Community
Advanced
zzafergokzzafergok
1

api-design-skill

Standardize REST and GraphQL API designs with consistent versioning and error formats.

Community
Intermediate
mescamesca

spec-driven

Align OpenAPI/OpenRPC contracts with Pydantic models and services.

Community
Intermediate