designing-apis

Name: designing-apis
Author: ancoleman

48installs59forks

How to install designing-apis?

ancoleman/ai-design-components/designing-apis

$npx -y skills add ancoleman/ai-design-components --skill designing-apis

Installs into the current project.

Summary

Design APIs that are secure, scalable, and maintainable using RESTful, GraphQL, and event-driven patterns. Use when designing new APIs, evolving existing APIs, or establishing API standards for teams.

Files · 1

View on GitHub

SKILL.md

1	# Designing APIs
2
3	Design well-structured, scalable APIs using REST, GraphQL, or event-driven patterns. Focus on resource design, versioning, error handling, pagination, rate limiting, and security.
4
5	## When to Use This Skill
6
7	Use when:
8	- Designing a new REST, GraphQL, or event-driven API
9	- Establishing API design standards for a team or organization
10	- Choosing between REST, GraphQL, WebSockets, or message queues
11	- Planning API versioning and breaking change management
12	- Defining error response formats and HTTP status code usage
13	- Implementing pagination, filtering, and rate limiting patterns
14	- Designing OAuth2 flows or API key authentication
15	- Creating OpenAPI or AsyncAPI specifications
16
17	Do NOT use for:
18	- Implementation code (use `api-patterns` skill for Express, FastAPI code)
19	- Authentication implementation (use `auth-security` skill for JWT, sessions)
20	- API testing strategies (use `testing-strategies` skill)
21	- API deployment and infrastructure (use `deploying-applications` skill)
22
23	## Core Design Principles
24
25	### Resource-Oriented Design (REST)
26
27	Use nouns for resources, not verbs in URLs:
28	```
29	✓ GET /users List users
30	✓ GET /users/123 Get user 123
31	✓ POST /users Create user
32	✓ PATCH /users/123 Update user 123
33	✓ DELETE /users/123 Delete user 123
34
35	✗ GET /getUsers
36	✗ POST /createUser
37	```
38
39	Nest resources for relationships (limit depth to 2-3 levels):
40	```
41	✓ GET /users/123/posts
42	✓ GET /users/123/posts/456/comments
43	✗ GET /users/123/posts/456/comments/789/replies (too deep)
44	```
45
46	For complete REST patterns, see references/rest-design.md
47
48	### HTTP Method Semantics
49
50	\| Method \| Idempotent \| Safe \| Use For \| Success Status \|
51	\|--------\|-----------\|------\|---------\|----------------\|
52	\| GET \| Yes \| Yes \| Read resource \| 200 OK \|
53	\| POST \| No \| No \| Create resource \| 201 Created \|
54	\| PUT \| Yes \| No \| Replace entire resource \| 200 OK, 204 No Content \|
55	\| PATCH \| No \| No \| Update specific fields \| 200 OK, 204 No Content \|
56	\| DELETE \| Yes \| No \| Remove resource \| 204 No Content, 200 OK \|
57
58	Idempotent means multiple identical requests have the same effect as one request.
59
60	### HTTP Status Codes
61
62	Success (2xx):
63	- 200 OK, 201 Created, 204 No Content
64
65	Client Errors (4xx):
66	- 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
67	- 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests
68
69	Server Errors (5xx):
70	- 500 Internal Server Error, 503 Service Unavailable
71
72	For complete status code guide, see references/rest-design.md
73
74	## API Style Selection
75
76	### Decision Matrix
77
78	\| Factor \| REST \| GraphQL \| WebSocket \| Message Queue \|
79	\|--------\|------\|---------\|-----------\|---------------\|
80	\| Public API \| ⭐⭐⭐⭐⭐ \| ⭐⭐⭐ \| ⭐⭐ \| ⭐ \|
81	\| Complex Data \| ⭐⭐⭐ \| ⭐⭐⭐⭐⭐ \| ⭐⭐ \| ⭐⭐ \|
82	\| Caching \| ⭐⭐⭐⭐⭐ \| ⭐⭐ \| ⭐ \| ⭐ \|
83	\| Real-time \| ⭐⭐ \| ⭐⭐⭐⭐ \| ⭐⭐⭐⭐⭐ \| ⭐⭐⭐⭐⭐ \|
84	\| Simplicity \| ⭐⭐⭐⭐⭐ \| ⭐⭐⭐ \| ⭐⭐⭐ \| ⭐⭐ \|
85
86	### Quick Selection
87
88	- Public API, CRUD operations → REST
89	- Complex data, flexible queries → GraphQL
90	- Real-time, bidirectional → WebSockets
91	- Event-driven, microservices → Message Queue
92
93	For detailed protocol selection, see references/protocol-selection.md
94
95	## API Versioning
96
97	### URL Path Versioning (Recommended)
98
99	```
100	https://api.example.com/v1/users
101	https://api.example.com/v2/users
102	```
103
104	Pros: Explicit, easy to implement and test
105	Cons: Maintenance overhead
106
107	### Alternative Strategies
108
109	- Header-Based: `Accept-Version: v1`
110	- Media Type: `Accept: application/vnd.example.v1+json`
111	- Query Parameter: `?version=1` (not recommended)
112
113	### Breaking Change Management
114
115	Timeline:
116	1. Month 0: Announce deprecation
117	2. Months 1-3: Migration period
118	3. Months 4-6: Deprecation warnings
119	4. Month 6: Sunset (return 410 Gone)
120
121	Include deprecation headers:
122	```http
123	Deprecation: true
124	Sunset: Sat, 31 Dec 2025 23:59:59 GMT
125	Link: </api/v2/users>; rel="successor-version"
126	```
127
128	For complete versioning guide, see references/versioning-strategies.md
129
130	## Error Response Standards
131
132	### RFC 7807 Problem Details (Recommended)
133
134	```json
135	{
136	"type": "https://api.example.com/errors/validation",
137	"title": "Validation Error",
138	"status": 400,
139	"detail": "One or more fields failed validation",
140	"errors": [
141	{
142	"field": "email",
143	"message": "Must be a valid email address",
144	"code": "INVALID_EMAIL"
145	}
146	]
147	}
148	```
149
150	Content-Type: `application/problem+json`
151
152	For complete error patterns, see references/error-handling.md
153
154	## Pagination Patterns
155
156	### Strategy Selection
157
158	\| Scenario \| Strategy \| Why \|
159	\|----------\|----------\|-----\|
160	\| Small datasets (<1000) \| Offset-based \| Simple, page numbers \|
161	\| Large datasets (>10K) \| Cursor-based \| Efficient, handles writes \|
162	\| Sorted data \| Keyset \| Consistent results \|
163	\| Real-time feeds \| Cursor-based \| Handles new items \|
164
165	###

People who liked this also viewed

6 picks

Type

designing-apis

48installs59forks

View on GitHub

How to install designing-apis?

ancoleman/ai-design-components/designing-apis

$npx -y skills add ancoleman/ai-design-components --skill designing-apis

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Designing APIs
2
3	Design well-structured, scalable APIs using REST, GraphQL, or event-driven patterns. Focus on resource design, versioning, error handling, pagination, rate limiting, and security.
4
5	## When to Use This Skill
6
7	Use when:
8	- Designing a new REST, GraphQL, or event-driven API
9	- Establishing API design standards for a team or organization
10	- Choosing between REST, GraphQL, WebSockets, or message queues
11	- Planning API versioning and breaking change management
12	- Defining error response formats and HTTP status code usage
13	- Implementing pagination, filtering, and rate limiting patterns
14	- Designing OAuth2 flows or API key authentication
15	- Creating OpenAPI or AsyncAPI specifications
16
17	Do NOT use for:
18	- Implementation code (use `api-patterns` skill for Express, FastAPI code)
19	- Authentication implementation (use `auth-security` skill for JWT, sessions)
20	- API testing strategies (use `testing-strategies` skill)
21	- API deployment and infrastructure (use `deploying-applications` skill)
22
23	## Core Design Principles
24
25	### Resource-Oriented Design (REST)
26
27	Use nouns for resources, not verbs in URLs:
28	```
29	✓ GET /users List users
30	✓ GET /users/123 Get user 123
31	✓ POST /users Create user
32	✓ PATCH /users/123 Update user 123
33	✓ DELETE /users/123 Delete user 123
34
35	✗ GET /getUsers
36	✗ POST /createUser
37	```
38
39	Nest resources for relationships (limit depth to 2-3 levels):
40	```
41	✓ GET /users/123/posts
42	✓ GET /users/123/posts/456/comments
43	✗ GET /users/123/posts/456/comments/789/replies (too deep)
44	```
45
46	For complete REST patterns, see references/rest-design.md
47
48	### HTTP Method Semantics
49
50	\| Method \| Idempotent \| Safe \| Use For \| Success Status \|
51	\|--------\|-----------\|------\|---------\|----------------\|
52	\| GET \| Yes \| Yes \| Read resource \| 200 OK \|
53	\| POST \| No \| No \| Create resource \| 201 Created \|
54	\| PUT \| Yes \| No \| Replace entire resource \| 200 OK, 204 No Content \|
55	\| PATCH \| No \| No \| Update specific fields \| 200 OK, 204 No Content \|
56	\| DELETE \| Yes \| No \| Remove resource \| 204 No Content, 200 OK \|
57
58	Idempotent means multiple identical requests have the same effect as one request.
59
60	### HTTP Status Codes
61
62	Success (2xx):
63	- 200 OK, 201 Created, 204 No Content
64
65	Client Errors (4xx):
66	- 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
67	- 409 Conflict, 422 Unprocessable Entity, 429 Too Many Requests
68
69	Server Errors (5xx):
70	- 500 Internal Server Error, 503 Service Unavailable
71
72	For complete status code guide, see references/rest-design.md
73
74	## API Style Selection
75
76	### Decision Matrix
77
78	\| Factor \| REST \| GraphQL \| WebSocket \| Message Queue \|
79	\|--------\|------\|---------\|-----------\|---------------\|
80	\| Public API \| ⭐⭐⭐⭐⭐ \| ⭐⭐⭐ \| ⭐⭐ \| ⭐ \|
81	\| Complex Data \| ⭐⭐⭐ \| ⭐⭐⭐⭐⭐ \| ⭐⭐ \| ⭐⭐ \|
82	\| Caching \| ⭐⭐⭐⭐⭐ \| ⭐⭐ \| ⭐ \| ⭐ \|
83	\| Real-time \| ⭐⭐ \| ⭐⭐⭐⭐ \| ⭐⭐⭐⭐⭐ \| ⭐⭐⭐⭐⭐ \|
84	\| Simplicity \| ⭐⭐⭐⭐⭐ \| ⭐⭐⭐ \| ⭐⭐⭐ \| ⭐⭐ \|
85
86	### Quick Selection
87
88	- Public API, CRUD operations → REST
89	- Complex data, flexible queries → GraphQL
90	- Real-time, bidirectional → WebSockets
91	- Event-driven, microservices → Message Queue
92
93	For detailed protocol selection, see references/protocol-selection.md
94
95	## API Versioning
96
97	### URL Path Versioning (Recommended)
98
99	```
100	https://api.example.com/v1/users
101	https://api.example.com/v2/users
102	```
103
104	Pros: Explicit, easy to implement and test
105	Cons: Maintenance overhead
106
107	### Alternative Strategies
108
109	- Header-Based: `Accept-Version: v1`
110	- Media Type: `Accept: application/vnd.example.v1+json`
111	- Query Parameter: `?version=1` (not recommended)
112
113	### Breaking Change Management
114
115	Timeline:
116	1. Month 0: Announce deprecation
117	2. Months 1-3: Migration period
118	3. Months 4-6: Deprecation warnings
119	4. Month 6: Sunset (return 410 Gone)
120
121	Include deprecation headers:
122	```http
123	Deprecation: true
124	Sunset: Sat, 31 Dec 2025 23:59:59 GMT
125	Link: </api/v2/users>; rel="successor-version"
126	```
127
128	For complete versioning guide, see references/versioning-strategies.md
129
130	## Error Response Standards
131
132	### RFC 7807 Problem Details (Recommended)
133
134	```json
135	{
136	"type": "https://api.example.com/errors/validation",
137	"title": "Validation Error",
138	"status": 400,
139	"detail": "One or more fields failed validation",
140	"errors": [
141	{
142	"field": "email",
143	"message": "Must be a valid email address",
144	"code": "INVALID_EMAIL"
145	}
146	]
147	}
148	```
149
150	Content-Type: `application/problem+json`
151
152	For complete error patterns, see references/error-handling.md
153
154	## Pagination Patterns
155
156	### Strategy Selection
157
158	\| Scenario \| Strategy \| Why \|
159	\|----------\|----------\|-----\|
160	\| Small datasets (<1000) \| Offset-based \| Simple, page numbers \|
161	\| Large datasets (>10K) \| Cursor-based \| Efficient, handles writes \|
162	\| Sorted data \| Keyset \| Consistent results \|
163	\| Real-time feeds \| Cursor-based \| Handles new items \|
164
165	###

People who liked this also viewed

6 picks

Type