majiayu000/spellbook / skills/api-design
api-design
VerifiedREST/GraphQL/gRPC API design best practices. Use when designing APIs, defining contracts, handling versioning. Covers OpenAPI 3.2, GraphQL Federation, gRPC streaming.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.3 KB |
| reference/comparison.md | markdown | 6.1 KB |
| reference/graphql.md | markdown | 6.2 KB |
| reference/grpc.md | markdown | 7.4 KB |
| reference/rest.md | markdown | 5.3 KB |
| templates/graphql/schema.graphql | other | 4.5 KB |
| templates/grpc/service.proto | other | 6.0 KB |
| templates/openapi/openapi.yaml | config | 8.3 KB |
templates/openapi/openapi.yaml
View on GitHubopenapi: 3.1.0
info:
title: Example API
description: REST API following best practices
version: 1.0.0
contact:
name: API Support
email: api@example.com
servers:
- url: https://api.example.com/v1
description: Production
- url: https://staging-api.example.com/v1
description: Staging
tags:
- name: Users
description: User management
- name: Orders
description: Order operations
paths:
/users:
get:
operationId: listUsers
tags: [Users]
summary: List users
parameters:
- $ref: '#/components/parameters/limitParam'
- $ref: '#/components/parameters/cursorParam'
- name: status
in: query
schema:
$ref: '#/components/schemas/UserStatus'
responses:
'200':
description: List of users
content:
application/json:
schema:
$ref: '#/components/schemas/UserListResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'429':
$ref: '#/components/responses/RateLimited'
post:
operationId: createUser
tags: [Users]
summary: Create a new user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateUserInput'
responses:
'201':
description: User created
headers:
Location:
schema:
type: string
description: URL of created resource
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'400':
$ref: '#/components/responses/BadRequest'
'409':
$ref: '#/components/responses/Conflict'
'422':
$ref: '#/components/responses/ValidationError'
/users/{id}:
parameters:
- $ref: '#/components/parameters/userIdParam'
get:
operationId: getUser
tags: [Users]
summary: Get user by ID
responses:
'200':
description: User found
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateUser
tags: [Users]
summary: Update user
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserInput'
responses:
'200':
description: User updated
content:
application/json:
schema:
$ref: '#/components/schemas/User'
'404':
$ref: '#/components/responses/NotFound'
'422':
$ref: '#/components/responses/ValidationError'
delete:
operationId: deleteUser
tags: [Users]
summary: Delete user
responses:
'204':
description: User deleted
'404':
$ref: '#/components/responses/NotFound'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
parameters:
userIdParam:
name: id
in: path
required: true
schema:
type: string
format: uuid
description: User ID
limitParam:
name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: Maximum items to return
cursorParam:
name: cursor
in: query
schema:
type: string
description: Pagination cursor
schemas:
User:
type: object
required:
- id
- email
- name
- status
- createdAt
properties:
id:
type: string
format: uuid
email:
type: string
format: email
name:
type: string
minLength: 2
maxLength: 100
status:
$ref: '#/components/schemas/UserStatus'
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
UserStatus:
type: string
enum: [active, inactive, suspended]
CreateUserInput:
type: object
required:
- email
- name
properties:
email:
type: string
format: email
name:
type: string
minLength: 2
maxLength: 100
UpdateUserInput:
type: object
properties:
name:
type: string
minLength: 2
maxLength: 100
status:
$ref: '#/components/schemas/UserStatus'
UserListResponse:
type: object
required:
- data
- pagination
properties:
data:
type: array
items:
$ref: '#/components/schemas/User'
pagination:
$ref: '#/components/schemas/Pagination'
Pagination:
type: object
required:
- hasNext
- limit
properties:
nextCursor:
type: string
prevCursor:
type: string
hasNext:
type: boolean
hasPrev:
type: boolean
limit:
type: integer
Error:
type: object
required:
- type
- title
- status
properties:
type:
type: string
format: uri
title:
type: string
status:
type: integer
detail:
type: string
instance:
type: string
errors:
type: array
items:
$ref: '#/components/schemas/FieldError'
FieldError:
type: object
required:
- field
- message
properties:
field:
type: string
message:
type: string
responses:
BadRequest:
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: https://api.example.com/errors/bad-request
title: Bad Request
status: 400
detail: The request body is malformed
Unauthorized:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: https://api.example.com/errors/unauthorized
title: Unauthorized
status: 401
detail: Missing or invalid authentication token
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: https://api.example.com/errors/not-found
title: Not Found
status: 404
detail: The requested resource was not found
Conflict:
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: https://api.example.com/errors/conflict
title: Conflict
status: 409
detail: A user with this email already exists
ValidationError:
description: Validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: https://api.example.com/errors/validation
title: Validation Error
status: 422
detail: The request contains invalid data
errors:
- field: email
message: Invalid email format
RateLimited:
description: Rate limited
headers:
X-RateLimit-Limit:
schema:
type: integer
X-RateLimit-Remaining:
schema:
type: integer
X-RateLimit-Reset:
schema:
type: integer
Retry-After:
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
type: https://api.example.com/errors/rate-limited
title: Rate Limit Exceeded
status: 429
detail: You have exceeded the rate limit
security:
- bearerAuth: []
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |