api-patterns

Name: api-patterns
Author: softspark

161stars21forks

How to install api-patterns?

softspark/ai-toolkit/api-patterns

$npx -y skills add softspark/ai-toolkit --skill api-patterns

Installs into the current project.

Summary

REST/GraphQL API design: naming, versioning, pagination, idempotency, OpenAPI. Triggers: API design, REST, GraphQL, OpenAPI, Swagger, idempotency, rate limit.

Files · 1

View on GitHub

SKILL.md

1	# API Patterns Skill
2
3	## REST API Design
4
5	### Resource Naming
6
7	```
8	# Collection
9	GET /api/v1/documents # List documents
10	POST /api/v1/documents # Create document
11
12	# Single resource
13	GET /api/v1/documents/{id} # Get document
14	PUT /api/v1/documents/{id} # Replace document
15	PATCH /api/v1/documents/{id} # Update document
16	DELETE /api/v1/documents/{id} # Delete document
17
18	# Nested resources
19	GET /api/v1/users/{id}/documents # User's documents
20	```
21
22	### HTTP Status Codes
23
24	\| Code \| Meaning \| When to Use \|
25	\|------\|---------\|-------------\|
26	\| 200 \| OK \| Successful GET/PUT/PATCH \|
27	\| 201 \| Created \| Successful POST \|
28	\| 204 \| No Content \| Successful DELETE \|
29	\| 400 \| Bad Request \| Invalid input \|
30	\| 401 \| Unauthorized \| Missing/invalid auth \|
31	\| 403 \| Forbidden \| No permission \|
32	\| 404 \| Not Found \| Resource doesn't exist \|
33	\| 409 \| Conflict \| Duplicate resource \|
34	\| 422 \| Unprocessable \| Validation error \|
35	\| 429 \| Too Many Requests \| Rate limited \|
36	\| 500 \| Internal Error \| Server error \|
37
38	### Response Format
39
40	```json
41	{
42	"data": {
43	"id": "123",
44	"type": "document",
45	"attributes": {
46	"title": "Example",
47	"content": "..."
48	}
49	},
50	"meta": {
51	"total": 100,
52	"page": 1,
53	"per_page": 10
54	}
55	}
56	```
57
58	### Error Response
59
60	```json
61	{
62	"error": {
63	"code": "VALIDATION_ERROR",
64	"message": "Invalid input",
65	"details": [
66	{"field": "title", "message": "Title is required"},
67	{"field": "limit", "message": "Must be between 1 and 100"}
68	]
69	}
70	}
71	```
72
73	---
74
75	## FastAPI Implementation
76
77	```python
78	from fastapi import FastAPI, HTTPException, Query, Path
79	from pydantic import BaseModel, Field
80
81	app = FastAPI(title="RAG-MCP API", version="1.0.0")
82
83	class SearchRequest(BaseModel):
84	query: str = Field(..., min_length=1, description="Search query")
85	limit: int = Field(10, ge=1, le=100, description="Max results")
86
87	class SearchResult(BaseModel):
88	id: str
89	title: str
90	score: float
91	content: str
92
93	class SearchResponse(BaseModel):
94	results: list[SearchResult]
95	total: int
96
97	@app.post("/api/v1/search", response_model=SearchResponse)
98	async def search(request: SearchRequest):
99	"""Search the knowledge base.
100
101	Args:
102	request: Search parameters
103
104	Returns:
105	Search results with scores
106	"""
107	try:
108	results = await perform_search(request.query, request.limit)
109	return SearchResponse(results=results, total=len(results))
110	except ValueError as e:
111	raise HTTPException(status_code=400, detail=str(e))
112	```
113
114	---
115
116	## Parameter Documentation Conventions
117
118	The same rules apply to OpenAPI `description` fields, Pydantic `Field(description=...)`, and MCP tool parameters: the description should encode the workflow, not just restate the type. A consumer (human or LLM) reads it to know how to supply a valid value, not what language primitive it is.
119
120	### Prefer enums with per-value descriptions for closed sets
121
122	A free-form `string` for `status` forces the caller to guess valid values. Constrain it and document each one:
123
124	```python
125	class ListReposRequest(BaseModel):
126	visibility: Literal["PUBLIC", "PRIVATE", "INTERNAL"] = Field(
127	"PUBLIC",
128	description=(
129	"Repository visibility filter. "
130	"PUBLIC = visible to anyone; "
131	"PRIVATE = only members with explicit access; "
132	"INTERNAL = visible to all org members (Enterprise only)."
133	),
134	)
135	```
136
137	In OpenAPI, pair `enum` with the value meanings in the description (or `x-enum-descriptions` if your tooling renders it). Avoid documenting a closed set as plain `string` — the caller cannot tell `INTERNAL` is valid but `internal` is not.
138
139	### Encode cross-field dependencies in the description
140
141	If a field is only valid given another, say so where the dependent field is defined — schemas cannot express "required when":
142
143	```python
144	cursor: str \| None = Field(
145	None,
146	description=(
147	"Pagination cursor. Requires a `next_cursor` value obtained from a prior "
148	"GET /api/v1/documents response. Omit on the first page; do not synthesize."
149	),
150	)
151	```
152
153	State the source call by name (`next_cursor` from the previous list response), not just "an opaque token".
154
155	### Add provenance and exactness constraints for opaque IDs
156
157	Opaque identifiers (resource IDs, idempotency keys, cursors) are the most common source of bad calls because they look like something the caller can invent. Pin them down:
158
159	```python
160	document_id: str = Field(
161	...,
162	description=(
163	"Exact document id, e.g. `doc_9f3a21`. Copy it verbatim from a search or "
164	"list response — case-sensitive, do not type from memory or guess the format. "
165	"Obtain it from GET /api/v1/documents or the search

People who liked this also viewed

6 picks

Type

hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026262k37k
request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026165k181k
analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026161k507
explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026161k507
ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026160k181k
scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026149k181k

api-patterns

161stars21forks

View on GitHub

How to install api-patterns?

softspark/ai-toolkit/api-patterns

$npx -y skills add softspark/ai-toolkit --skill api-patterns

Installs into the current project.

Summary

REST/GraphQL API design: naming, versioning, pagination, idempotency, OpenAPI. Triggers: API design, REST, GraphQL, OpenAPI, Swagger, idempotency, rate limit.

Files · 1

View on GitHub

SKILL.md

1	# API Patterns Skill
2
3	## REST API Design
4
5	### Resource Naming
6
7	```
8	# Collection
9	GET /api/v1/documents # List documents
10	POST /api/v1/documents # Create document
11
12	# Single resource
13	GET /api/v1/documents/{id} # Get document
14	PUT /api/v1/documents/{id} # Replace document
15	PATCH /api/v1/documents/{id} # Update document
16	DELETE /api/v1/documents/{id} # Delete document
17
18	# Nested resources
19	GET /api/v1/users/{id}/documents # User's documents
20	```
21
22	### HTTP Status Codes
23
24	\| Code \| Meaning \| When to Use \|
25	\|------\|---------\|-------------\|
26	\| 200 \| OK \| Successful GET/PUT/PATCH \|
27	\| 201 \| Created \| Successful POST \|
28	\| 204 \| No Content \| Successful DELETE \|
29	\| 400 \| Bad Request \| Invalid input \|
30	\| 401 \| Unauthorized \| Missing/invalid auth \|
31	\| 403 \| Forbidden \| No permission \|
32	\| 404 \| Not Found \| Resource doesn't exist \|
33	\| 409 \| Conflict \| Duplicate resource \|
34	\| 422 \| Unprocessable \| Validation error \|
35	\| 429 \| Too Many Requests \| Rate limited \|
36	\| 500 \| Internal Error \| Server error \|
37
38	### Response Format
39
40	```json
41	{
42	"data": {
43	"id": "123",
44	"type": "document",
45	"attributes": {
46	"title": "Example",
47	"content": "..."
48	}
49	},
50	"meta": {
51	"total": 100,
52	"page": 1,
53	"per_page": 10
54	}
55	}
56	```
57
58	### Error Response
59
60	```json
61	{
62	"error": {
63	"code": "VALIDATION_ERROR",
64	"message": "Invalid input",
65	"details": [
66	{"field": "title", "message": "Title is required"},
67	{"field": "limit", "message": "Must be between 1 and 100"}
68	]
69	}
70	}
71	```
72
73	---
74
75	## FastAPI Implementation
76
77	```python
78	from fastapi import FastAPI, HTTPException, Query, Path
79	from pydantic import BaseModel, Field
80
81	app = FastAPI(title="RAG-MCP API", version="1.0.0")
82
83	class SearchRequest(BaseModel):
84	query: str = Field(..., min_length=1, description="Search query")
85	limit: int = Field(10, ge=1, le=100, description="Max results")
86
87	class SearchResult(BaseModel):
88	id: str
89	title: str
90	score: float
91	content: str
92
93	class SearchResponse(BaseModel):
94	results: list[SearchResult]
95	total: int
96
97	@app.post("/api/v1/search", response_model=SearchResponse)
98	async def search(request: SearchRequest):
99	"""Search the knowledge base.
100
101	Args:
102	request: Search parameters
103
104	Returns:
105	Search results with scores
106	"""
107	try:
108	results = await perform_search(request.query, request.limit)
109	return SearchResponse(results=results, total=len(results))
110	except ValueError as e:
111	raise HTTPException(status_code=400, detail=str(e))
112	```
113
114	---
115
116	## Parameter Documentation Conventions
117
118	The same rules apply to OpenAPI `description` fields, Pydantic `Field(description=...)`, and MCP tool parameters: the description should encode the workflow, not just restate the type. A consumer (human or LLM) reads it to know how to supply a valid value, not what language primitive it is.
119
120	### Prefer enums with per-value descriptions for closed sets
121
122	A free-form `string` for `status` forces the caller to guess valid values. Constrain it and document each one:
123
124	```python
125	class ListReposRequest(BaseModel):
126	visibility: Literal["PUBLIC", "PRIVATE", "INTERNAL"] = Field(
127	"PUBLIC",
128	description=(
129	"Repository visibility filter. "
130	"PUBLIC = visible to anyone; "
131	"PRIVATE = only members with explicit access; "
132	"INTERNAL = visible to all org members (Enterprise only)."
133	),
134	)
135	```
136
137	In OpenAPI, pair `enum` with the value meanings in the description (or `x-enum-descriptions` if your tooling renders it). Avoid documenting a closed set as plain `string` — the caller cannot tell `INTERNAL` is valid but `internal` is not.
138
139	### Encode cross-field dependencies in the description
140
141	If a field is only valid given another, say so where the dependent field is defined — schemas cannot express "required when":
142
143	```python
144	cursor: str \| None = Field(
145	None,
146	description=(
147	"Pagination cursor. Requires a `next_cursor` value obtained from a prior "
148	"GET /api/v1/documents response. Omit on the first page; do not synthesize."
149	),
150	)
151	```
152
153	State the source call by name (`next_cursor` from the previous list response), not just "an opaque token".
154
155	### Add provenance and exactness constraints for opaque IDs
156
157	Opaque identifiers (resource IDs, idempotency keys, cursors) are the most common source of bad calls because they look like something the caller can invent. Pin them down:
158
159	```python
160	document_id: str = Field(
161	...,
162	description=(
163	"Exact document id, e.g. `doc_9f3a21`. Copy it verbatim from a search or "
164	"list response — case-sensitive, do not type from memory or guess the format. "
165	"Obtain it from GET /api/v1/documents or the search

People who liked this also viewed

6 picks

Type