skills.rest
p-o-ke-nae
p-o-ke-naeCOMMUNITY
Explore all skills by this author →
GitHub

api-design-principles

Design REST and GraphQL API structures with versioning, pagination, and error handling.

Updated May 16, 2026
Search Tags:#versioning#api design#openapi#rest#graphql#pagination#data loaders
One-click install
npx skills add https://github.com/p-o-ke-nae/pokemondamagecalculatorforstory --skill api-design-principles-p-o-ke-nae
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/p-o-ke-nae/pokemondamagecalculatorforstory/tree/main/.github/skills/api-design-principles
Command: npx skills add https://github.com/p-o-ke-nae/pokemondamagecalculatorforstory --skill api-design-principles-p-o-ke-nae

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

This Skill helps you turn vague API ideas into clear, consistent, and scalable designs that are easier to implement, document, and maintain.

Core Features & Use Cases

  • REST Guidance: Choose resource-oriented URLs, correct HTTP methods, pagination, filtering, versioning, and error handling patterns.
  • GraphQL Guidance: Shape schemas, inputs, payloads, resolvers, subscriptions, and pagination with strong typing and maintainability in mind.
  • Practical Reviews: Use it to evaluate an API spec before implementation, improve an existing endpoint set, or standardize team-wide API conventions for a product.

Quick Start

Ask the skill to review your API design or draft a REST or GraphQL endpoint plan for a specific product feature.

Frequently Asked Questions about api-design-principles

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

FAQPage Schema
How do I design REST API endpoints that are intuitive and scalable?▼

Design REST API endpoints using resource-oriented URLs, correct HTTP semantics, consistent status codes, and standardized pagination. This approach ensures your API contracts remain intuitive, scalable, and maintainable for developers.

What is the best way to prevent N+1 query problems in GraphQL API design?▼

Prevent GraphQL N+1 query problems by implementing DataLoader-based batching within your resolvers. This pattern groups multiple requests into a single batch, ensuring scalable and maintainable schema-first data fetching.

How do I structure API versioning and error handling for a new product feature?▼

Structure API versioning and error handling by applying consistent validation, correct HTTP status codes, and standardized error payloads. This standardizes team-wide conventions for a product and improves endpoint maintainability.

Can I use this to review an existing OpenAPI specification before implementation?▼

Yes, you can review an existing OpenAPI specification before implementation. It evaluates API specs against schema-first modeling, pagination, and validation rules to improve an existing endpoint set.

When should I choose GraphQL over REST for my API architecture?▼

Choose GraphQL for strong typing, complex schema inputs, and subscriptions, while choosing REST for resource-oriented endpoints and standard HTTP methods. Both require consistent validation and maintainable contracts.

Does this API design approach support GraphQL subscriptions and pagination?▼

Yes, this approach supports GraphQL subscriptions and pagination. It shapes schemas, inputs, and payloads with strong typing and maintainability in mind, covering both REST and GraphQL API design workflows.

Related Skills

Explore More Software Engineering Skills→
GenerativeAgentsGenerativeAgents

prd-writing

Generate a review-ready PRD from initial-requirements.md using the PRD template.

Official
Advanced
camilooscargbaptistacamilooscargbaptista
7

api-documentation

Generate and review OpenAPI 3.1 specs for REST and GraphQL APIs.

Community
Intermediate
kibertoadkibertoad
1

add-api-query

Automate data fetching and mutation with API contracts, typed HTTP client, and React Query.

Community
Intermediate
jolequesjoleques

api-documentador-revisor

Validate API documentation completeness and consistency, then produce a Markdown revision report.

Community
Intermediate