@ranimontagna/agent-toolkit 0.1.10 → 0.1.12
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +16 -2
- package/package.json +1 -1
- package/skills/backend/api/api-design/LICENSE +21 -0
- package/skills/backend/api/api-design/NOTICE.md +7 -0
- package/skills/backend/api/api-design/SKILL.md +523 -0
- package/skills/frontend/astro/astro-developer/LICENSE +59 -0
- package/skills/frontend/astro/astro-developer/NOTICE.md +7 -0
- package/skills/frontend/astro/astro-developer/SKILL.md +132 -0
- package/skills/frontend/astro/astro-developer/architecture.md +435 -0
- package/skills/frontend/astro/astro-developer/constraints.md +559 -0
- package/skills/frontend/astro/astro-developer/debugging.md +513 -0
- package/skills/frontend/astro/astro-developer/testing.md +973 -0
package/README.md
CHANGED
|
@@ -129,6 +129,9 @@ skills/
|
|
|
129
129
|
agent-toolkit-maintainer/
|
|
130
130
|
SKILL.md
|
|
131
131
|
backend/
|
|
132
|
+
api/
|
|
133
|
+
api-design/
|
|
134
|
+
SKILL.md
|
|
132
135
|
database/
|
|
133
136
|
postgres-patterns/
|
|
134
137
|
SKILL.md
|
|
@@ -158,6 +161,13 @@ skills/
|
|
|
158
161
|
frontend/
|
|
159
162
|
accessibility/
|
|
160
163
|
SKILL.md
|
|
164
|
+
astro/
|
|
165
|
+
astro-developer/
|
|
166
|
+
SKILL.md
|
|
167
|
+
architecture.md
|
|
168
|
+
constraints.md
|
|
169
|
+
debugging.md
|
|
170
|
+
testing.md
|
|
161
171
|
design/
|
|
162
172
|
ui-ux-pro-max/
|
|
163
173
|
SKILL.md
|
|
@@ -272,6 +282,7 @@ Follow these steps...
|
|
|
272
282
|
| Package | Skill | Source |
|
|
273
283
|
|---|---|---|
|
|
274
284
|
| `core` | `agent-toolkit-maintainer` | Maintained in this repository |
|
|
285
|
+
| `backend` | `api-design` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/api-design) under the MIT license |
|
|
275
286
|
| `backend` | `postgres-patterns` | Adapted from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/.kiro/skills/postgres-patterns) and [`sickn33/antigravity-awesome-skills`](https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/postgresql), both under the MIT license |
|
|
276
287
|
| `backend` | `fastify-best-practices` | Copied from Matteo Collina's [`mcollina/skills`](https://github.com/mcollina/skills/tree/main/skills/fastify) under the MIT license |
|
|
277
288
|
| `backend` | `golang-patterns` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/golang-patterns) under the MIT license |
|
|
@@ -284,6 +295,7 @@ Follow these steps...
|
|
|
284
295
|
| `backend` | `python-testing` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/.kiro/skills/python-testing) under the MIT license |
|
|
285
296
|
| `devops` | `docker-patterns` | Adapted from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/.kiro/skills/docker-patterns) and [`sickn33/antigravity-awesome-skills`](https://github.com/sickn33/antigravity-awesome-skills/tree/main/skills/docker-expert), both under the MIT license |
|
|
286
297
|
| `frontend` | `accessibility` | Copied from Affaan Mustafa's [`ECC`](https://github.com/affaan-m/ECC/tree/main/skills/accessibility) under the MIT license |
|
|
298
|
+
| `frontend` | `astro-developer` | Copied from the official [`withastro/astro`](https://github.com/withastro/astro/tree/main/.agents/skills/astro-developer) repository under the MIT license |
|
|
287
299
|
| `frontend` | `ui-ux-pro-max` | Copied from Next Level Builder's [`ui-ux-pro-max-skill`](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill/tree/main/.claude/skills/ui-ux-pro-max) under the MIT license |
|
|
288
300
|
| `frontend` | `react-native-expert` | Copied from Jeffallan's [`claude-skills`](https://github.com/Jeffallan/claude-skills/tree/main/skills/react-native-expert) under the MIT license |
|
|
289
301
|
| `frontend` | `react-native-unistyles-v3` | Copied from Jacek Pudysz's [`react-native-unistyles`](https://github.com/jpudysz/react-native-unistyles/tree/main/skills/react-native-unistyles-v3), declared MIT upstream |
|
|
@@ -428,7 +440,9 @@ Bundled third-party skills preserve upstream attribution and license files:
|
|
|
428
440
|
|
|
429
441
|
| Skill | Source commit | License |
|
|
430
442
|
|---|---|---|
|
|
443
|
+
| `api-design` | `affaan-m/ECC@0f84c0e2796703fbda87d577b2636351418c7442` | MIT |
|
|
431
444
|
| `fastify-best-practices` | `mcollina/skills@5b2a81354b6d10325da0db9decc9ce5ecc714138` | MIT |
|
|
445
|
+
| `astro-developer` | `withastro/astro@c90ce9751c7862a7280e752549ef74298669693d` | MIT |
|
|
432
446
|
| `react-native-expert` | `Jeffallan/claude-skills@e8be415bc94d8d6ebddc2fb50e5d03c6e27d4319` | MIT |
|
|
433
447
|
| `react-native-unistyles-v3` | `jpudysz/react-native-unistyles@8b5e9fd281a81bdfd87d4fe9e6a0b042c84c5c83` | MIT |
|
|
434
448
|
| `react-patterns` | `affaan-m/ECC@0f84c0e2796703fbda87d577b2636351418c7442` | MIT |
|
|
@@ -552,8 +566,8 @@ Release a new npm version by updating `package.json`, pushing the change to
|
|
|
552
566
|
`main`, then pushing a matching tag:
|
|
553
567
|
|
|
554
568
|
```bash
|
|
555
|
-
git tag v0.1.
|
|
556
|
-
git push origin v0.1.
|
|
569
|
+
git tag v0.1.12
|
|
570
|
+
git push origin v0.1.12
|
|
557
571
|
```
|
|
558
572
|
|
|
559
573
|
The `Release` workflow runs the full check and publishes the scoped package to
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ranimontagna/agent-toolkit",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.12",
|
|
4
4
|
"description": "Personal AI agent toolkit installer for Claude Code, Codex CLI, OpenCode, Gemini CLI and graph-aware workflows.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"packageManager": "pnpm@11.0.6",
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Affaan Mustafa
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,523 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: api-design
|
|
3
|
+
description: Use when designing, reviewing, or implementing REST APIs, including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting.
|
|
4
|
+
origin: ECC
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# API Design Patterns
|
|
8
|
+
|
|
9
|
+
Conventions and best practices for designing consistent, developer-friendly REST APIs.
|
|
10
|
+
|
|
11
|
+
## When to Activate
|
|
12
|
+
|
|
13
|
+
- Designing new API endpoints
|
|
14
|
+
- Reviewing existing API contracts
|
|
15
|
+
- Adding pagination, filtering, or sorting
|
|
16
|
+
- Implementing error handling for APIs
|
|
17
|
+
- Planning API versioning strategy
|
|
18
|
+
- Building public or partner-facing APIs
|
|
19
|
+
|
|
20
|
+
## Resource Design
|
|
21
|
+
|
|
22
|
+
### URL Structure
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
# Resources are nouns, plural, lowercase, kebab-case
|
|
26
|
+
GET /api/v1/users
|
|
27
|
+
GET /api/v1/users/:id
|
|
28
|
+
POST /api/v1/users
|
|
29
|
+
PUT /api/v1/users/:id
|
|
30
|
+
PATCH /api/v1/users/:id
|
|
31
|
+
DELETE /api/v1/users/:id
|
|
32
|
+
|
|
33
|
+
# Sub-resources for relationships
|
|
34
|
+
GET /api/v1/users/:id/orders
|
|
35
|
+
POST /api/v1/users/:id/orders
|
|
36
|
+
|
|
37
|
+
# Actions that don't map to CRUD (use verbs sparingly)
|
|
38
|
+
POST /api/v1/orders/:id/cancel
|
|
39
|
+
POST /api/v1/auth/login
|
|
40
|
+
POST /api/v1/auth/refresh
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
### Naming Rules
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
# GOOD
|
|
47
|
+
/api/v1/team-members # kebab-case for multi-word resources
|
|
48
|
+
/api/v1/orders?status=active # query params for filtering
|
|
49
|
+
/api/v1/users/123/orders # nested resources for ownership
|
|
50
|
+
|
|
51
|
+
# BAD
|
|
52
|
+
/api/v1/getUsers # verb in URL
|
|
53
|
+
/api/v1/user # singular (use plural)
|
|
54
|
+
/api/v1/team_members # snake_case in URLs
|
|
55
|
+
/api/v1/users/123/getOrders # verb in nested resource
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
## HTTP Methods and Status Codes
|
|
59
|
+
|
|
60
|
+
### Method Semantics
|
|
61
|
+
|
|
62
|
+
| Method | Idempotent | Safe | Use For |
|
|
63
|
+
|--------|-----------|------|---------|
|
|
64
|
+
| GET | Yes | Yes | Retrieve resources |
|
|
65
|
+
| POST | No | No | Create resources, trigger actions |
|
|
66
|
+
| PUT | Yes | No | Full replacement of a resource |
|
|
67
|
+
| PATCH | No* | No | Partial update of a resource |
|
|
68
|
+
| DELETE | Yes | No | Remove a resource |
|
|
69
|
+
|
|
70
|
+
*PATCH can be made idempotent with proper implementation
|
|
71
|
+
|
|
72
|
+
### Status Code Reference
|
|
73
|
+
|
|
74
|
+
```
|
|
75
|
+
# Success
|
|
76
|
+
200 OK — GET, PUT, PATCH (with response body)
|
|
77
|
+
201 Created — POST (include Location header)
|
|
78
|
+
204 No Content — DELETE, PUT (no response body)
|
|
79
|
+
|
|
80
|
+
# Client Errors
|
|
81
|
+
400 Bad Request — Validation failure, malformed JSON
|
|
82
|
+
401 Unauthorized — Missing or invalid authentication
|
|
83
|
+
403 Forbidden — Authenticated but not authorized
|
|
84
|
+
404 Not Found — Resource doesn't exist
|
|
85
|
+
409 Conflict — Duplicate entry, state conflict
|
|
86
|
+
422 Unprocessable Entity — Semantically invalid (valid JSON, bad data)
|
|
87
|
+
429 Too Many Requests — Rate limit exceeded
|
|
88
|
+
|
|
89
|
+
# Server Errors
|
|
90
|
+
500 Internal Server Error — Unexpected failure (never expose details)
|
|
91
|
+
502 Bad Gateway — Upstream service failed
|
|
92
|
+
503 Service Unavailable — Temporary overload, include Retry-After
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### Common Mistakes
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
# BAD: 200 for everything
|
|
99
|
+
{ "status": 200, "success": false, "error": "Not found" }
|
|
100
|
+
|
|
101
|
+
# GOOD: Use HTTP status codes semantically
|
|
102
|
+
HTTP/1.1 404 Not Found
|
|
103
|
+
{ "error": { "code": "not_found", "message": "User not found" } }
|
|
104
|
+
|
|
105
|
+
# BAD: 500 for validation errors
|
|
106
|
+
# GOOD: 400 or 422 with field-level details
|
|
107
|
+
|
|
108
|
+
# BAD: 200 for created resources
|
|
109
|
+
# GOOD: 201 with Location header
|
|
110
|
+
HTTP/1.1 201 Created
|
|
111
|
+
Location: /api/v1/users/abc-123
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## Response Format
|
|
115
|
+
|
|
116
|
+
### Success Response
|
|
117
|
+
|
|
118
|
+
```json
|
|
119
|
+
{
|
|
120
|
+
"data": {
|
|
121
|
+
"id": "abc-123",
|
|
122
|
+
"email": "alice@example.com",
|
|
123
|
+
"name": "Alice",
|
|
124
|
+
"created_at": "2025-01-15T10:30:00Z"
|
|
125
|
+
}
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Collection Response (with Pagination)
|
|
130
|
+
|
|
131
|
+
```json
|
|
132
|
+
{
|
|
133
|
+
"data": [
|
|
134
|
+
{ "id": "abc-123", "name": "Alice" },
|
|
135
|
+
{ "id": "def-456", "name": "Bob" }
|
|
136
|
+
],
|
|
137
|
+
"meta": {
|
|
138
|
+
"total": 142,
|
|
139
|
+
"page": 1,
|
|
140
|
+
"per_page": 20,
|
|
141
|
+
"total_pages": 8
|
|
142
|
+
},
|
|
143
|
+
"links": {
|
|
144
|
+
"self": "/api/v1/users?page=1&per_page=20",
|
|
145
|
+
"next": "/api/v1/users?page=2&per_page=20",
|
|
146
|
+
"last": "/api/v1/users?page=8&per_page=20"
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
### Error Response
|
|
152
|
+
|
|
153
|
+
```json
|
|
154
|
+
{
|
|
155
|
+
"error": {
|
|
156
|
+
"code": "validation_error",
|
|
157
|
+
"message": "Request validation failed",
|
|
158
|
+
"details": [
|
|
159
|
+
{
|
|
160
|
+
"field": "email",
|
|
161
|
+
"message": "Must be a valid email address",
|
|
162
|
+
"code": "invalid_format"
|
|
163
|
+
},
|
|
164
|
+
{
|
|
165
|
+
"field": "age",
|
|
166
|
+
"message": "Must be between 0 and 150",
|
|
167
|
+
"code": "out_of_range"
|
|
168
|
+
}
|
|
169
|
+
]
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
### Response Envelope Variants
|
|
175
|
+
|
|
176
|
+
```typescript
|
|
177
|
+
// Option A: Envelope with data wrapper (recommended for public APIs)
|
|
178
|
+
interface ApiResponse<T> {
|
|
179
|
+
data: T;
|
|
180
|
+
meta?: PaginationMeta;
|
|
181
|
+
links?: PaginationLinks;
|
|
182
|
+
}
|
|
183
|
+
|
|
184
|
+
interface ApiError {
|
|
185
|
+
error: {
|
|
186
|
+
code: string;
|
|
187
|
+
message: string;
|
|
188
|
+
details?: FieldError[];
|
|
189
|
+
};
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
// Option B: Flat response (simpler, common for internal APIs)
|
|
193
|
+
// Success: just return the resource directly
|
|
194
|
+
// Error: return error object
|
|
195
|
+
// Distinguish by HTTP status code
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Pagination
|
|
199
|
+
|
|
200
|
+
### Offset-Based (Simple)
|
|
201
|
+
|
|
202
|
+
```
|
|
203
|
+
GET /api/v1/users?page=2&per_page=20
|
|
204
|
+
|
|
205
|
+
# Implementation
|
|
206
|
+
SELECT * FROM users
|
|
207
|
+
ORDER BY created_at DESC
|
|
208
|
+
LIMIT 20 OFFSET 20;
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
**Pros:** Easy to implement, supports "jump to page N"
|
|
212
|
+
**Cons:** Slow on large offsets (OFFSET 100000), inconsistent with concurrent inserts
|
|
213
|
+
|
|
214
|
+
### Cursor-Based (Scalable)
|
|
215
|
+
|
|
216
|
+
```
|
|
217
|
+
GET /api/v1/users?cursor=eyJpZCI6MTIzfQ&limit=20
|
|
218
|
+
|
|
219
|
+
# Implementation
|
|
220
|
+
SELECT * FROM users
|
|
221
|
+
WHERE id > :cursor_id
|
|
222
|
+
ORDER BY id ASC
|
|
223
|
+
LIMIT 21; -- fetch one extra to determine has_next
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
```json
|
|
227
|
+
{
|
|
228
|
+
"data": [...],
|
|
229
|
+
"meta": {
|
|
230
|
+
"has_next": true,
|
|
231
|
+
"next_cursor": "eyJpZCI6MTQzfQ"
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
**Pros:** Consistent performance regardless of position, stable with concurrent inserts
|
|
237
|
+
**Cons:** Cannot jump to arbitrary page, cursor is opaque
|
|
238
|
+
|
|
239
|
+
### When to Use Which
|
|
240
|
+
|
|
241
|
+
| Use Case | Pagination Type |
|
|
242
|
+
|----------|----------------|
|
|
243
|
+
| Admin dashboards, small datasets (<10K) | Offset |
|
|
244
|
+
| Infinite scroll, feeds, large datasets | Cursor |
|
|
245
|
+
| Public APIs | Cursor (default) with offset (optional) |
|
|
246
|
+
| Search results | Offset (users expect page numbers) |
|
|
247
|
+
|
|
248
|
+
## Filtering, Sorting, and Search
|
|
249
|
+
|
|
250
|
+
### Filtering
|
|
251
|
+
|
|
252
|
+
```
|
|
253
|
+
# Simple equality
|
|
254
|
+
GET /api/v1/orders?status=active&customer_id=abc-123
|
|
255
|
+
|
|
256
|
+
# Comparison operators (use bracket notation)
|
|
257
|
+
GET /api/v1/products?price[gte]=10&price[lte]=100
|
|
258
|
+
GET /api/v1/orders?created_at[after]=2025-01-01
|
|
259
|
+
|
|
260
|
+
# Multiple values (comma-separated)
|
|
261
|
+
GET /api/v1/products?category=electronics,clothing
|
|
262
|
+
|
|
263
|
+
# Nested fields (dot notation)
|
|
264
|
+
GET /api/v1/orders?customer.country=US
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
### Sorting
|
|
268
|
+
|
|
269
|
+
```
|
|
270
|
+
# Single field (prefix - for descending)
|
|
271
|
+
GET /api/v1/products?sort=-created_at
|
|
272
|
+
|
|
273
|
+
# Multiple fields (comma-separated)
|
|
274
|
+
GET /api/v1/products?sort=-featured,price,-created_at
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
### Full-Text Search
|
|
278
|
+
|
|
279
|
+
```
|
|
280
|
+
# Search query parameter
|
|
281
|
+
GET /api/v1/products?q=wireless+headphones
|
|
282
|
+
|
|
283
|
+
# Field-specific search
|
|
284
|
+
GET /api/v1/users?email=alice
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
### Sparse Fieldsets
|
|
288
|
+
|
|
289
|
+
```
|
|
290
|
+
# Return only specified fields (reduces payload)
|
|
291
|
+
GET /api/v1/users?fields=id,name,email
|
|
292
|
+
GET /api/v1/orders?fields=id,total,status&include=customer.name
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
## Authentication and Authorization
|
|
296
|
+
|
|
297
|
+
### Token-Based Auth
|
|
298
|
+
|
|
299
|
+
```
|
|
300
|
+
# Bearer token in Authorization header
|
|
301
|
+
GET /api/v1/users
|
|
302
|
+
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
|
|
303
|
+
|
|
304
|
+
# API key (for server-to-server)
|
|
305
|
+
GET /api/v1/data
|
|
306
|
+
X-API-Key: example-api-key-placeholder
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
### Authorization Patterns
|
|
310
|
+
|
|
311
|
+
```typescript
|
|
312
|
+
// Resource-level: check ownership
|
|
313
|
+
app.get("/api/v1/orders/:id", async (req, res) => {
|
|
314
|
+
const order = await Order.findById(req.params.id);
|
|
315
|
+
if (!order) return res.status(404).json({ error: { code: "not_found" } });
|
|
316
|
+
if (order.userId !== req.user.id) return res.status(403).json({ error: { code: "forbidden" } });
|
|
317
|
+
return res.json({ data: order });
|
|
318
|
+
});
|
|
319
|
+
|
|
320
|
+
// Role-based: check permissions
|
|
321
|
+
app.delete("/api/v1/users/:id", requireRole("admin"), async (req, res) => {
|
|
322
|
+
await User.delete(req.params.id);
|
|
323
|
+
return res.status(204).send();
|
|
324
|
+
});
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
## Rate Limiting
|
|
328
|
+
|
|
329
|
+
### Headers
|
|
330
|
+
|
|
331
|
+
```
|
|
332
|
+
HTTP/1.1 200 OK
|
|
333
|
+
X-RateLimit-Limit: 100
|
|
334
|
+
X-RateLimit-Remaining: 95
|
|
335
|
+
X-RateLimit-Reset: 1640000000
|
|
336
|
+
|
|
337
|
+
# When exceeded
|
|
338
|
+
HTTP/1.1 429 Too Many Requests
|
|
339
|
+
Retry-After: 60
|
|
340
|
+
{
|
|
341
|
+
"error": {
|
|
342
|
+
"code": "rate_limit_exceeded",
|
|
343
|
+
"message": "Rate limit exceeded. Try again in 60 seconds."
|
|
344
|
+
}
|
|
345
|
+
}
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
### Rate Limit Tiers
|
|
349
|
+
|
|
350
|
+
| Tier | Limit | Window | Use Case |
|
|
351
|
+
|------|-------|--------|----------|
|
|
352
|
+
| Anonymous | 30/min | Per IP | Public endpoints |
|
|
353
|
+
| Authenticated | 100/min | Per user | Standard API access |
|
|
354
|
+
| Premium | 1000/min | Per API key | Paid API plans |
|
|
355
|
+
| Internal | 10000/min | Per service | Service-to-service |
|
|
356
|
+
|
|
357
|
+
## Versioning
|
|
358
|
+
|
|
359
|
+
### URL Path Versioning (Recommended)
|
|
360
|
+
|
|
361
|
+
```
|
|
362
|
+
/api/v1/users
|
|
363
|
+
/api/v2/users
|
|
364
|
+
```
|
|
365
|
+
|
|
366
|
+
**Pros:** Explicit, easy to route, cacheable
|
|
367
|
+
**Cons:** URL changes between versions
|
|
368
|
+
|
|
369
|
+
### Header Versioning
|
|
370
|
+
|
|
371
|
+
```
|
|
372
|
+
GET /api/users
|
|
373
|
+
Accept: application/vnd.myapp.v2+json
|
|
374
|
+
```
|
|
375
|
+
|
|
376
|
+
**Pros:** Clean URLs
|
|
377
|
+
**Cons:** Harder to test, easy to forget
|
|
378
|
+
|
|
379
|
+
### Versioning Strategy
|
|
380
|
+
|
|
381
|
+
```
|
|
382
|
+
1. Start with /api/v1/ — don't version until you need to
|
|
383
|
+
2. Maintain at most 2 active versions (current + previous)
|
|
384
|
+
3. Deprecation timeline:
|
|
385
|
+
- Announce deprecation (6 months notice for public APIs)
|
|
386
|
+
- Add Sunset header: Sunset: Sat, 01 Jan 2026 00:00:00 GMT
|
|
387
|
+
- Return 410 Gone after sunset date
|
|
388
|
+
4. Non-breaking changes don't need a new version:
|
|
389
|
+
- Adding new fields to responses
|
|
390
|
+
- Adding new optional query parameters
|
|
391
|
+
- Adding new endpoints
|
|
392
|
+
5. Breaking changes require a new version:
|
|
393
|
+
- Removing or renaming fields
|
|
394
|
+
- Changing field types
|
|
395
|
+
- Changing URL structure
|
|
396
|
+
- Changing authentication method
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
## Implementation Patterns
|
|
400
|
+
|
|
401
|
+
### TypeScript (Next.js API Route)
|
|
402
|
+
|
|
403
|
+
```typescript
|
|
404
|
+
import { z } from "zod";
|
|
405
|
+
import { NextRequest, NextResponse } from "next/server";
|
|
406
|
+
|
|
407
|
+
const createUserSchema = z.object({
|
|
408
|
+
email: z.string().email(),
|
|
409
|
+
name: z.string().min(1).max(100),
|
|
410
|
+
});
|
|
411
|
+
|
|
412
|
+
export async function POST(req: NextRequest) {
|
|
413
|
+
const body = await req.json();
|
|
414
|
+
const parsed = createUserSchema.safeParse(body);
|
|
415
|
+
|
|
416
|
+
if (!parsed.success) {
|
|
417
|
+
return NextResponse.json({
|
|
418
|
+
error: {
|
|
419
|
+
code: "validation_error",
|
|
420
|
+
message: "Request validation failed",
|
|
421
|
+
details: parsed.error.issues.map(i => ({
|
|
422
|
+
field: i.path.join("."),
|
|
423
|
+
message: i.message,
|
|
424
|
+
code: i.code,
|
|
425
|
+
})),
|
|
426
|
+
},
|
|
427
|
+
}, { status: 422 });
|
|
428
|
+
}
|
|
429
|
+
|
|
430
|
+
const user = await createUser(parsed.data);
|
|
431
|
+
|
|
432
|
+
return NextResponse.json(
|
|
433
|
+
{ data: user },
|
|
434
|
+
{
|
|
435
|
+
status: 201,
|
|
436
|
+
headers: { Location: `/api/v1/users/${user.id}` },
|
|
437
|
+
},
|
|
438
|
+
);
|
|
439
|
+
}
|
|
440
|
+
```
|
|
441
|
+
|
|
442
|
+
### Python (Django REST Framework)
|
|
443
|
+
|
|
444
|
+
```python
|
|
445
|
+
from rest_framework import serializers, viewsets, status
|
|
446
|
+
from rest_framework.response import Response
|
|
447
|
+
|
|
448
|
+
class CreateUserSerializer(serializers.Serializer):
|
|
449
|
+
email = serializers.EmailField()
|
|
450
|
+
name = serializers.CharField(max_length=100)
|
|
451
|
+
|
|
452
|
+
class UserSerializer(serializers.ModelSerializer):
|
|
453
|
+
class Meta:
|
|
454
|
+
model = User
|
|
455
|
+
fields = ["id", "email", "name", "created_at"]
|
|
456
|
+
|
|
457
|
+
class UserViewSet(viewsets.ModelViewSet):
|
|
458
|
+
serializer_class = UserSerializer
|
|
459
|
+
permission_classes = [IsAuthenticated]
|
|
460
|
+
|
|
461
|
+
def get_serializer_class(self):
|
|
462
|
+
if self.action == "create":
|
|
463
|
+
return CreateUserSerializer
|
|
464
|
+
return UserSerializer
|
|
465
|
+
|
|
466
|
+
def create(self, request):
|
|
467
|
+
serializer = CreateUserSerializer(data=request.data)
|
|
468
|
+
serializer.is_valid(raise_exception=True)
|
|
469
|
+
user = UserService.create(**serializer.validated_data)
|
|
470
|
+
return Response(
|
|
471
|
+
{"data": UserSerializer(user).data},
|
|
472
|
+
status=status.HTTP_201_CREATED,
|
|
473
|
+
headers={"Location": f"/api/v1/users/{user.id}"},
|
|
474
|
+
)
|
|
475
|
+
```
|
|
476
|
+
|
|
477
|
+
### Go (net/http)
|
|
478
|
+
|
|
479
|
+
```go
|
|
480
|
+
func (h *UserHandler) CreateUser(w http.ResponseWriter, r *http.Request) {
|
|
481
|
+
var req CreateUserRequest
|
|
482
|
+
if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
|
|
483
|
+
writeError(w, http.StatusBadRequest, "invalid_json", "Invalid request body")
|
|
484
|
+
return
|
|
485
|
+
}
|
|
486
|
+
|
|
487
|
+
if err := req.Validate(); err != nil {
|
|
488
|
+
writeError(w, http.StatusUnprocessableEntity, "validation_error", err.Error())
|
|
489
|
+
return
|
|
490
|
+
}
|
|
491
|
+
|
|
492
|
+
user, err := h.service.Create(r.Context(), req)
|
|
493
|
+
if err != nil {
|
|
494
|
+
switch {
|
|
495
|
+
case errors.Is(err, domain.ErrEmailTaken):
|
|
496
|
+
writeError(w, http.StatusConflict, "email_taken", "Email already registered")
|
|
497
|
+
default:
|
|
498
|
+
writeError(w, http.StatusInternalServerError, "internal_error", "Internal error")
|
|
499
|
+
}
|
|
500
|
+
return
|
|
501
|
+
}
|
|
502
|
+
|
|
503
|
+
w.Header().Set("Location", fmt.Sprintf("/api/v1/users/%s", user.ID))
|
|
504
|
+
writeJSON(w, http.StatusCreated, map[string]any{"data": user})
|
|
505
|
+
}
|
|
506
|
+
```
|
|
507
|
+
|
|
508
|
+
## API Design Checklist
|
|
509
|
+
|
|
510
|
+
Before shipping a new endpoint:
|
|
511
|
+
|
|
512
|
+
- [ ] Resource URL follows naming conventions (plural, kebab-case, no verbs)
|
|
513
|
+
- [ ] Correct HTTP method used (GET for reads, POST for creates, etc.)
|
|
514
|
+
- [ ] Appropriate status codes returned (not 200 for everything)
|
|
515
|
+
- [ ] Input validated with schema (Zod, Pydantic, Bean Validation)
|
|
516
|
+
- [ ] Error responses follow standard format with codes and messages
|
|
517
|
+
- [ ] Pagination implemented for list endpoints (cursor or offset)
|
|
518
|
+
- [ ] Authentication required (or explicitly marked as public)
|
|
519
|
+
- [ ] Authorization checked (user can only access their own resources)
|
|
520
|
+
- [ ] Rate limiting configured
|
|
521
|
+
- [ ] Response does not leak internal details (stack traces, SQL errors)
|
|
522
|
+
- [ ] Consistent naming with existing endpoints (camelCase vs snake_case)
|
|
523
|
+
- [ ] Documented (OpenAPI/Swagger spec updated)
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2021 Fred K. Schott
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
23
|
+
"""
|
|
24
|
+
This license applies to parts of the `packages/create-astro` and `packages/astro` subdirectories originating from the https://github.com/sveltejs/kit repository:
|
|
25
|
+
|
|
26
|
+
Copyright (c) 2020 [these people](https://github.com/sveltejs/kit/graphs/contributors)
|
|
27
|
+
|
|
28
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
29
|
+
|
|
30
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
31
|
+
|
|
32
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
33
|
+
"""
|
|
34
|
+
|
|
35
|
+
"""
|
|
36
|
+
This license applies to parts of the `packages/create-astro` and `packages/astro` subdirectories originating from the https://github.com/vitejs/vite repository:
|
|
37
|
+
|
|
38
|
+
MIT License
|
|
39
|
+
|
|
40
|
+
Copyright (c) 2019-present, Yuxi (Evan) You and Vite contributors
|
|
41
|
+
|
|
42
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
43
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
44
|
+
in the Software without restriction, including without limitation the rights
|
|
45
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
46
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
47
|
+
furnished to do so, subject to the following conditions:
|
|
48
|
+
|
|
49
|
+
The above copyright notice and this permission notice shall be included in all
|
|
50
|
+
copies or substantial portions of the Software.
|
|
51
|
+
|
|
52
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
53
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
54
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
55
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
56
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
57
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
58
|
+
SOFTWARE.
|
|
59
|
+
"""
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Attribution
|
|
2
|
+
|
|
3
|
+
This skill is copied from the official Astro repository, `.agents/skills/astro-developer`, commit `c90ce9751c7862a7280e752549ef74298669693d`.
|
|
4
|
+
|
|
5
|
+
Source: https://github.com/withastro/astro/tree/main/.agents/skills/astro-developer
|
|
6
|
+
|
|
7
|
+
License: MIT. See `LICENSE`.
|