api-design-principles

Name: api-design-principles
Author: wshobson

25kinstalls4.1kforks

How to install api-design-principles?

wshobson/agents/api-design-principles

$npx -y skills add wshobson/agents --skill api-design-principles

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

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

People who liked this also viewed

6 picks

Type

api-design-principles

25kinstalls4.1kforks

View on GitHub

How to install api-design-principles?

wshobson/agents/api-design-principles

$npx -y skills add wshobson/agents --skill api-design-principles

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

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

People who liked this also viewed

6 picks

Type