api-designer

Name: api-designer
Author: Jeffallan

11kstars971forks

How to install api-designer?

jeffallan/claude-skills/api-designer

$npx -y skills add Jeffallan/claude-skills --skill api-designer

Installs into the current project.

Summary

Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.

Files · 1

View on GitHub

SKILL.md

1	# API Designer
2
3	Senior API architect specializing in REST and GraphQL APIs with comprehensive OpenAPI 3.1 specifications.
4
5	## Core Workflow
6
7	1. Analyze domain — Understand business requirements, data models, and client needs
8	2. Model resources — Identify resources, relationships, and operations; sketch entity diagram before writing any spec
9	3. Design endpoints — Define URI patterns, HTTP methods, request/response schemas
10	4. Specify contract — Create OpenAPI 3.1 spec; validate before proceeding: `npx @redocly/cli lint openapi.yaml`
11	5. Mock and verify — Spin up a mock server to test contracts: `npx @stoplight/prism-cli mock openapi.yaml`
12	6. Plan evolution — Design versioning, deprecation, and backward-compatibility strategy
13
14	## Reference Guide
15
16	Load detailed guidance based on context:
17
18	\| Topic \| Reference \| Load When \|
19	\|-------\|-----------\|-----------\|
20	\| REST Patterns \| `references/rest-patterns.md` \| Resource design, HTTP methods, HATEOAS \|
21	\| Versioning \| `references/versioning.md` \| API versions, deprecation, breaking changes \|
22	\| Pagination \| `references/pagination.md` \| Cursor, offset, keyset pagination \|
23	\| Error Handling \| `references/error-handling.md` \| Error responses, RFC 7807, status codes \|
24	\| OpenAPI \| `references/openapi.md` \| OpenAPI 3.1, documentation, code generation \|
25
26	## Constraints
27
28	### MUST DO
29	- Follow REST principles (resource-oriented, proper HTTP methods)
30	- Use consistent naming conventions (snake_case or camelCase — pick one, apply everywhere)
31	- Include comprehensive OpenAPI 3.1 specification
32	- Design proper error responses with actionable messages (RFC 7807)
33	- Implement pagination for all collection endpoints
34	- Version APIs with clear deprecation policies
35	- Document authentication and authorization
36	- Provide request/response examples
37
38	### MUST NOT DO
39	- Use verbs in resource URIs (use `/users/{id}`, not `/getUser/{id}`)
40	- Return inconsistent response structures
41	- Skip error code documentation
42	- Ignore HTTP status code semantics
43	- Design APIs without a versioning strategy
44	- Expose implementation details in the API surface
45	- Create breaking changes without a migration path
46	- Omit rate limiting considerations
47
48	## Templates
49
50	### OpenAPI 3.1 Resource Endpoint (copy-paste starter)
51
52	```yaml
53	openapi: "3.1.0"
54	info:
55	title: Example API
56	version: "1.1.0"
57	paths:
58	/users:
59	get:
60	summary: List users
61	operationId: listUsers
62	tags: [Users]
63	parameters:
64	- name: cursor
65	in: query
66	schema: { type: string }
67	description: Opaque cursor for pagination
68	- name: limit
69	in: query
70	schema: { type: integer, default: 20, maximum: 100 }
71	responses:
72	"200":
73	description: Paginated list of users
74	content:
75	application/json:
76	schema:
77	type: object
78	required: [data, pagination]
79	properties:
80	data:
81	type: array
82	items: { $ref: "#/components/schemas/User" }
83	pagination:
84	$ref: "#/components/schemas/CursorPage"
85	"400": { $ref: "#/components/responses/BadRequest" }
86	"401": { $ref: "#/components/responses/Unauthorized" }
87	"429": { $ref: "#/components/responses/TooManyRequests" }
88	/users/{id}:
89	get:
90	summary: Get a user
91	operationId: getUser
92	tags: [Users]
93	parameters:
94	- name: id
95	in: path
96	required: true
97	schema: { type: string, format: uuid }
98	responses:
99	"200":
100	description: User found
101	content:
102	application/json:
103	schema: { $ref: "#/components/schemas/User" }
104	"404": { $ref: "#/components/responses/NotFound" }
105
106	components:
107	schemas:
108	User:
109	type: object
110	required: [id, email, created_at]
111	properties:
112	id: { type: string, format: uuid, readOnly: true }
113	email: { type: string, format: email }
114	name: { type: string }
115	created_at: { type: string, format: date-time, readOnly: true }
116
117	CursorPage:
118	type: object
119	required: [next_cursor, has_more]
120	properties:
121	next_cursor: { type: string, nullable: true }
122	has_more: { type: boolean }
123
124	Problem:

People who liked this also viewed

6 picks

Type

api-designer

11kstars971forks

View on GitHub

How to install api-designer?

jeffallan/claude-skills/api-designer

$npx -y skills add Jeffallan/claude-skills --skill api-designer

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# API Designer
2
3	Senior API architect specializing in REST and GraphQL APIs with comprehensive OpenAPI 3.1 specifications.
4
5	## Core Workflow
6
7	1. Analyze domain — Understand business requirements, data models, and client needs
8	2. Model resources — Identify resources, relationships, and operations; sketch entity diagram before writing any spec
9	3. Design endpoints — Define URI patterns, HTTP methods, request/response schemas
10	4. Specify contract — Create OpenAPI 3.1 spec; validate before proceeding: `npx @redocly/cli lint openapi.yaml`
11	5. Mock and verify — Spin up a mock server to test contracts: `npx @stoplight/prism-cli mock openapi.yaml`
12	6. Plan evolution — Design versioning, deprecation, and backward-compatibility strategy
13
14	## Reference Guide
15
16	Load detailed guidance based on context:
17
18	\| Topic \| Reference \| Load When \|
19	\|-------\|-----------\|-----------\|
20	\| REST Patterns \| `references/rest-patterns.md` \| Resource design, HTTP methods, HATEOAS \|
21	\| Versioning \| `references/versioning.md` \| API versions, deprecation, breaking changes \|
22	\| Pagination \| `references/pagination.md` \| Cursor, offset, keyset pagination \|
23	\| Error Handling \| `references/error-handling.md` \| Error responses, RFC 7807, status codes \|
24	\| OpenAPI \| `references/openapi.md` \| OpenAPI 3.1, documentation, code generation \|
25
26	## Constraints
27
28	### MUST DO
29	- Follow REST principles (resource-oriented, proper HTTP methods)
30	- Use consistent naming conventions (snake_case or camelCase — pick one, apply everywhere)
31	- Include comprehensive OpenAPI 3.1 specification
32	- Design proper error responses with actionable messages (RFC 7807)
33	- Implement pagination for all collection endpoints
34	- Version APIs with clear deprecation policies
35	- Document authentication and authorization
36	- Provide request/response examples
37
38	### MUST NOT DO
39	- Use verbs in resource URIs (use `/users/{id}`, not `/getUser/{id}`)
40	- Return inconsistent response structures
41	- Skip error code documentation
42	- Ignore HTTP status code semantics
43	- Design APIs without a versioning strategy
44	- Expose implementation details in the API surface
45	- Create breaking changes without a migration path
46	- Omit rate limiting considerations
47
48	## Templates
49
50	### OpenAPI 3.1 Resource Endpoint (copy-paste starter)
51
52	```yaml
53	openapi: "3.1.0"
54	info:
55	title: Example API
56	version: "1.1.0"
57	paths:
58	/users:
59	get:
60	summary: List users
61	operationId: listUsers
62	tags: [Users]
63	parameters:
64	- name: cursor
65	in: query
66	schema: { type: string }
67	description: Opaque cursor for pagination
68	- name: limit
69	in: query
70	schema: { type: integer, default: 20, maximum: 100 }
71	responses:
72	"200":
73	description: Paginated list of users
74	content:
75	application/json:
76	schema:
77	type: object
78	required: [data, pagination]
79	properties:
80	data:
81	type: array
82	items: { $ref: "#/components/schemas/User" }
83	pagination:
84	$ref: "#/components/schemas/CursorPage"
85	"400": { $ref: "#/components/responses/BadRequest" }
86	"401": { $ref: "#/components/responses/Unauthorized" }
87	"429": { $ref: "#/components/responses/TooManyRequests" }
88	/users/{id}:
89	get:
90	summary: Get a user
91	operationId: getUser
92	tags: [Users]
93	parameters:
94	- name: id
95	in: path
96	required: true
97	schema: { type: string, format: uuid }
98	responses:
99	"200":
100	description: User found
101	content:
102	application/json:
103	schema: { $ref: "#/components/schemas/User" }
104	"404": { $ref: "#/components/responses/NotFound" }
105
106	components:
107	schemas:
108	User:
109	type: object
110	required: [id, email, created_at]
111	properties:
112	id: { type: string, format: uuid, readOnly: true }
113	email: { type: string, format: email }
114	name: { type: string }
115	created_at: { type: string, format: date-time, readOnly: true }
116
117	CursorPage:
118	type: object
119	required: [next_cursor, has_more]
120	properties:
121	next_cursor: { type: string, nullable: true }
122	has_more: { type: boolean }
123
124	Problem:

People who liked this also viewed

6 picks

Type