skills.rest
sawrus
sawrusCOMMUNITY
Explore all skills by this author →
GitHub

api-design-principles

Design REST and GraphQL APIs with schema-first patterns and versioning.

17|4|Updated Feb 4, 2026
Search Tags:#design#versioning#documentation#GraphQL#REST#patterns#APIs
One-click install
npx skills add https://github.com/sawrus/agent-guides --skill api-design-principles-sawrus
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-principles
Source: https://github.com/sawrus/agent-guides/tree/main/skills/api-design-principles
Command: npx skills add https://github.com/sawrus/agent-guides --skill api-design-principles-sawrus

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Designing consistent, scalable, and developer-friendly REST and GraphQL APIs is challenging without a structured design standard. This Skill codifies best practices, patterns, and templates to help teams ship robust APIs that are easy to learn and hard to break.

Core Features & Use Cases

  • Schema-First Guidance: Define resources, types, and contracts before implementation.
  • Pattern Toolkit: Pagination, versioning, error handling, and authentication strategies with concrete examples.
  • Reference & Playbooks: Leverage implementation playbooks and templates to standardize design reviews, API docs, and governance.
  • Use Case: When designing a new REST API or reviewing an API spec, apply these principles to create a stable, documented interface.

Quick Start

  1. Start with a resources/implementation-playbook.md to align on patterns.
  2. Review an OpenAPI/Swagger spec and GraphQL schema against the playbooks.
  3. Produce a concise API Design Standard document for your team.

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 consistent REST and GraphQL APIs?▼

Design REST and GraphQL APIs using a schema-first approach to define resources and types before implementation, ensuring contracts are stable and scalable across your team.

What's the best way to version REST APIs and handle pagination?▼

Apply standard versioning and pagination patterns from an implementation playbook to maintain backward compatibility and manage large datasets efficiently across REST and GraphQL.

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

Standardize error handling by adopting consistent error formats and authentication strategies defined in API design playbooks, making interfaces predictable and easy to debug.

When do I need schema-first API design?▼

You need schema-first API design when creating a new REST API or reviewing a spec, allowing you to define types and contracts upfront to prevent breaking changes later.

Can I use these API design principles to review an existing OpenAPI spec?▼

Yes, you can review an existing OpenAPI or Swagger spec against the provided implementation playbooks to validate pagination, versioning, and error handling standards.

REST vs GraphQL: how do I choose the right API design pattern?▼

Compare REST and GraphQL patterns by evaluating your data fetching requirements, using the toolkit to apply the appropriate pagination, versioning, and documentation strategies for your use case.

Related Skills

Explore More Software Engineering Skills→
SaturateSaturate

api-design

Generate OpenAPI specs and TypeScript types from contract-first API designs.

Community
Advanced
k-negishik-negishi
1

development-guidelines

Standardize development practices with centralized guidelines and templates.

Community
Intermediate
cornmanwtfcornmanwtf

contract-first-api-development

Author OpenAPI and AsyncAPI specifications and generate mock servers.

Community
Intermediate
aexol-studioaexol-studio
27

axolotl-schema

Generate type-safe GraphQL models and resolver boilerplates from a schema.

Official
Intermediate