api-design-principles

Design REST and GraphQL APIs with resource modeling, versioning, and error handling patterns.

1|Updated Jan 30, 2026
One-click install
npx skills add https://github.com/jieni777/opencode-config-backup --skill api-design-principles-jieni777
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/jieni777/opencode-config-backup/tree/main/skills/api-design-principles
Command: npx skills add https://github.com/jieni777/opencode-config-backup --skill api-design-principles-jieni777

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

API design principles help teams create consistent, scalable, and maintainable REST and GraphQL APIs, reducing ambiguity and fragmentation across services.

Core Features & Use Cases

  • Resource modeling guidelines for REST and schemas for GraphQL that promote interoperability.
  • Versioning, pagination, error handling, and security patterns to streamline evolution.
  • Practical templates and checklists (playbooks) to accelerate design reviews and standards adoption.

Quick Start

Review an existing API specification and align it with the playbook described in resources/implementation-playbook.md

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 and GraphQL APIs for consistency and scalability?

To design REST and GraphQL APIs for consistency and scalability, apply structured guidelines covering resource modeling, versioning, pagination, error handling, and schema design to reduce fragmentation across services.

What is the best way to handle API versioning and pagination?

The best way to handle API versioning and pagination is to apply standardized patterns that streamline API evolution, ensuring backward compatibility while managing large datasets efficiently across REST and GraphQL workflows.

How do I model resources for REST and design schemas for GraphQL?

Model REST resources and design GraphQL schemas using established interoperability guidelines that promote structured data representation, ensuring maintainable and consistent API endpoints across your enterprise architecture.

Can I use these API design principles for enterprise-level requirements?

Yes, these API design principles suit enterprise requirements by enforcing structured guidance through compiled playbooks, checklists, and example schemas that ensure standard adoption and architectural consistency.

How do I review an existing API specification against best practices?

Review an existing API specification against best practices by aligning it with an implementation playbook that provides structured checklists, practical templates, and standardized patterns for design reviews.

Why does API error handling matter for service interoperability?

API error handling matters for service interoperability because standardized error patterns streamline debugging and evolution, reducing ambiguity and fragmentation across distributed REST and GraphQL services.