api-design-principles

Evaluate REST and GraphQL API designs for consistency and maintainability.

Updated Aug 23, 2026

Search Tags:#versioning #documentation #error handling #api design #rest #graphql #pagination

Ready to run

npx skills add https://github.com/diegocondo10/sinai-intranet-backend --skill api-design-principles-diegocondo10

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/diegocondo10/sinai-intranet-backend/tree/main/.agents/skills/api-design-principles
Command: npx skills add https://github.com/diegocondo10/sinai-intranet-backend --skill api-design-principles-diegocondo10

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill helps teams design and evaluate APIs that are predictable, scalable, and easy for developers to use, reducing friction from inconsistent endpoints, weak error handling, and unclear documentation.

Core Features & Use Cases

REST design review: Checks resource naming, HTTP method semantics, pagination, filtering, versioning, and status codes.
GraphQL schema guidance: Helps structure queries, mutations, payloads, pagination, and resolver patterns while avoiding N+1 issues.
Production readiness: Covers authentication, authorization, rate limiting, caching, monitoring, and testing.
Use case: Review a new user management API before launch to catch inconsistent routes, missing validation, and unsafe response formats.

Quick Start

Ask the Skill to review your API specification and return concrete improvements for endpoints, errors, pagination, security, and documentation.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema

How do I review my REST API design for consistency and correct HTTP semantics?▼

To review a REST API design, evaluate resource-oriented naming, correct HTTP method semantics, pagination metadata, filtering, versioning, and status codes to ensure endpoint clarity and maintainability.

What is the best way to structure GraphQL schemas to avoid N+1 query problems?▼

The best way to avoid N+1 problems in GraphQL schema design is to structure queries, mutations, and payloads effectively while applying specific resolver pattern checks to ensure safe and efficient data fetching.

How do you handle API error handling and pagination for production readiness?▼

Handle API error handling and pagination by implementing structured error formats and pagination metadata, ensuring production readiness through consistent response structures across all endpoints.

Does this API design review work for both REST and GraphQL specifications?▼

Yes, the API design review applies to both REST and GraphQL schemas, evaluating endpoint structure, schema validation, authentication, and safety checks against breaking changes for predictable APIs.

How do I check my API specification for breaking changes before launch?▼

Check an API specification for breaking changes before launch by running safety checks against schema validation, resource-oriented naming, and structured error formats to catch inconsistent routes and unsafe responses.

What should I include in API documentation reviews to reduce developer friction?▼

API documentation reviews should include endpoint structure, pagination metadata, authentication methods, and structured error formats to reduce friction from unclear documentation and inconsistent endpoints.