Master REST and GraphQL API design principles to build

by wshobson · MIT license · ★ 39,857 on GitHub · updated Sep 21

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.

---
name: api-design-principles
description: Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.
---

# API Design Principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.

## When to Use This Skill

- Designing new REST or GraphQL APIs
- Refactoring existing APIs for better usability
- Establishing API design standards for your team
- Reviewing API specifications before implementation
- Migrating between API paradigms (REST to GraphQL, etc.)
- Creating developer-friendly API documentation
- Optimizing APIs for specific use cases (mobile, third-party integrations)

Overview

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.

Manual install (npx, ZIP)

Claude Codenpx skills add wshobson/agents --skill api-design-principles -g -a claude-code

Claude Code (manual)

mkdir -p ~/.claude/skills && curl -sL https://codeload.github.com/wshobson/agents/tar.gz/4236bb91f839 \
  | tar -xz -C ~/.claude/skills --strip-components=4 agents-4236bb91f839/plugins/backend-development/skills/api-design-principles

Windows (PowerShell)

New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null; Invoke-WebRequest "https://m.agentalley.io/zip/2681722254ce3537c2b0/api-design-principles.zip" -OutFile "$env:TEMP\api-design-principles.zip"; Expand-Archive "$env:TEMP\api-design-principles.zip" -DestinationPath "$HOME\.claude\skills" -Force

Claude.ai / desktopDownload the ZIP and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md3.5 KB
assets/2 files · 9.0 KB
references/3 files · 25.8 KB

Read the files here

wshobson/4236bb96 files

SKILL.md3.5 KB

SKILL.md

Show the full text111 lines

api-design-principles/SKILL.md111 lines · 3.5 KB

PreviewCode

Outline

RawView on GitHub

API Design Principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.

When to Use This Skill

Designing new REST or GraphQL APIs
Refactoring existing APIs for better usability
Establishing API design standards for your team
Reviewing API specifications before implementation
Migrating between API paradigms (REST to GraphQL, etc.)
Creating developer-friendly API documentation
Optimizing APIs for specific use cases (mobile, third-party integrations)

Core Concepts

1. RESTful Design Principles

Resource-Oriented Architecture

Resources are nouns (users, orders, products), not verbs
Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)
URLs represent resource hierarchies
Consistent naming conventions

HTTP Methods Semantics:

GET: Retrieve resources (idempotent, safe)
POST: Create new resources
PUT: Replace entire resource (idempotent)
PATCH: Partial resource updates
DELETE: Remove resources (idempotent)

2. GraphQL Design Principles

Schema-First Development

Types define your domain model
Queries for reading data
Mutations for modifying data
Subscriptions for real-time updates

Query Structure:

Clients request exactly what they need
Single endpoint, multiple operations
Strongly typed schema
Introspection built-in

3. API Versioning Strategies

URL Versioning:

/api/v1/users
/api/v2/users

Header Versioning:

Accept: application/vnd.api+json; version=1

Query Parameter Versioning:

/api/users?version=1

Detailed patterns and worked examples

Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.

Best Practices

REST APIs

Consistent Naming: Use plural nouns for collections (/users, not /user)
Stateless: Each request contains all necessary information
Use HTTP Status Codes Correctly: 2xx success, 4xx client errors, 5xx server errors
Version Your API: Plan for breaking changes from day one
Pagination: Always paginate large collections
Rate Limiting: Protect your API with rate limits
Documentation: Use OpenAPI/Swagger for interactive docs

GraphQL APIs

Schema First: Design schema before writing resolvers
Avoid N+1: Use DataLoaders for efficient data fetching
Input Validation: Validate at schema and resolver levels
Error Handling: Return structured errors in mutation payloads
Pagination: Use cursor-based pagination (Relay spec)
Deprecation: Use @deprecated directive for gradual migration
Monitoring: Track query complexity and execution time

Common Pitfalls

Over-fetching/Under-fetching (REST): Fixed in GraphQL but requires DataLoaders
Breaking Changes: Version APIs or use deprecation strategies
Inconsistent Error Formats: Standardize error responses
Missing Rate Limits: APIs without limits are vulnerable to abuse
Poor Documentation: Undocumented APIs frustrate developers
Ignoring HTTP Semantics: POST for idempotent operations breaks expectations
Tight Coupling: API structure shouldn't mirror database schema

1	---
2	name: api-design-principles
3	description: Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.
4	---
5
6	# API Design Principles
7
8	Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.
9
10	## When to Use This Skill
11
12	- Designing new REST or GraphQL APIs
13	- Refactoring existing APIs for better usability
14	- Establishing API design standards for your team
15	- Reviewing API specifications before implementation
16	- Migrating between API paradigms (REST to GraphQL, etc.)
17	- Creating developer-friendly API documentation
18	- Optimizing APIs for specific use cases (mobile, third-party integrations)
19
20	## Core Concepts
21
22	### 1. RESTful Design Principles
23
24	Resource-Oriented Architecture
25
26	- Resources are nouns (users, orders, products), not verbs
27	- Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)
28	- URLs represent resource hierarchies
29	- Consistent naming conventions
30
31	HTTP Methods Semantics:
32
33	- `GET`: Retrieve resources (idempotent, safe)
34	- `POST`: Create new resources
35	- `PUT`: Replace entire resource (idempotent)
36	- `PATCH`: Partial resource updates
37	- `DELETE`: Remove resources (idempotent)
38
39	### 2. GraphQL Design Principles
40
41	Schema-First Development
42
43	- Types define your domain model
44	- Queries for reading data
45	- Mutations for modifying data
46	- Subscriptions for real-time updates
47
48	Query Structure:
49
50	- Clients request exactly what they need
51	- Single endpoint, multiple operations
52	- Strongly typed schema
53	- Introspection built-in
54
55	### 3. API Versioning Strategies
56
57	URL Versioning:
58
59	```
60	/api/v1/users
61	/api/v2/users
62	```
63
64	Header Versioning:
65
66	```
67	Accept: application/vnd.api+json; version=1
68	```
69
70	Query Parameter Versioning:
71
72	```
73	/api/users?version=1
74	```
75
76	## Detailed patterns and worked examples
77
78	Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.
79
80	## Best Practices
81
82	### REST APIs
83
84	1. Consistent Naming: Use plural nouns for collections (`/users`, not `/user`)
85	2. Stateless: Each request contains all necessary information
86	3. Use HTTP Status Codes Correctly: 2xx success, 4xx client errors, 5xx server errors
87	4. Version Your API: Plan for breaking changes from day one
88	5. Pagination: Always paginate large collections
89	6. Rate Limiting: Protect your API with rate limits
90	7. Documentation: Use OpenAPI/Swagger for interactive docs
91
92	### GraphQL APIs
93
94	1. Schema First: Design schema before writing resolvers
95	2. Avoid N+1: Use DataLoaders for efficient data fetching
96	3. Input Validation: Validate at schema and resolver levels
97	4. Error Handling: Return structured errors in mutation payloads
98	5. Pagination: Use cursor-based pagination (Relay spec)
99	6. Deprecation: Use `@deprecated` directive for gradual migration
100	7. Monitoring: Track query complexity and execution time
101
102	## Common Pitfalls
103
104	- Over-fetching/Under-fetching (REST): Fixed in GraphQL but requires DataLoaders
105	- Breaking Changes: Version APIs or use deprecation strategies
106	- Inconsistent Error Formats: Standardize error responses
107	- Missing Rate Limits: APIs without limits are vulnerable to abuse
108	- Poor Documentation: Undocumented APIs frustrate developers
109	- Ignoring HTTP Semantics: POST for idempotent operations breaks expectations
110	- Tight Coupling: API structure shouldn't mirror database schema
111