Skip to content

Latest commit

 

History

History

api-design-principles

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 

README.md

API Design Principles

Design intuitive, scalable REST and GraphQL APIs that developers love. Covers resource modeling, HTTP semantics, pagination, error handling, versioning, and GraphQL schema patterns.

What's Inside

  • Decision Framework — REST vs GraphQL comparison
  • REST API Design — resource naming rules, HTTP methods and status codes, complete status code reference
  • Pagination — offset-based and cursor-based strategies
  • Filtering and Sorting patterns
  • Error Response Format with consistent structure
  • FastAPI Implementation example with CRUD, pagination, and filtering
  • GraphQL API Design — schema structure, Relay-style pagination, input/payload mutation pattern
  • DataLoader for N+1 prevention
  • Query Protection — depth limiting, complexity limiting, timeout
  • Versioning Strategies — URL versioning, header versioning, deprecation strategy
  • Rate Limiting headers and implementation
  • Pre-Implementation Checklist — resources, HTTP, data, security, documentation

When to Use

  • Designing new REST or GraphQL APIs
  • Reviewing API specifications before implementation
  • Establishing API design standards for teams
  • Refactoring APIs for better usability
  • Migrating between API paradigms

Installation

npx add https://github.com/wpank/ai/tree/main/skills/backend/api-design-principles

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install api-design-principles

Manual Installation

Cursor (per-project)

From your project root:

mkdir -p .cursor/skills
cp -r ~/.ai-skills/skills/backend/api-design-principles .cursor/skills/api-design-principles

Cursor (global)

mkdir -p ~/.cursor/skills
cp -r ~/.ai-skills/skills/backend/api-design-principles ~/.cursor/skills/api-design-principles

Claude Code (per-project)

From your project root:

mkdir -p .claude/skills
cp -r ~/.ai-skills/skills/backend/api-design-principles .claude/skills/api-design-principles

Claude Code (global)

mkdir -p ~/.claude/skills
cp -r ~/.ai-skills/skills/backend/api-design-principles ~/.claude/skills/api-design-principles

Part of the Backend skill category.