/api
Design REST or GraphQL API endpoints with schemas and validation.
Usage
code
/api <action> [resource] [--type <type>] [--methods <methods>]
Arguments
- •
action:design,scaffold,document,validate - •
resource: Resource name (e.g.,users,orders) - •
--type: API type (rest,graphql) (default: rest) - •
--methods: HTTP methods to include (default: all CRUD)
Instructions
When this skill is invoked:
Agent Behavior
Autonomy:
- •Complete API design/scaffold end-to-end
- •Follow REST/GraphQL best practices
- •Generate OpenAPI/GraphQL schema
Quality:
- •Consistent naming conventions
- •Proper HTTP status codes
- •Comprehensive validation
- •Security considerations
Actions
Design (/api design <resource>)
Create API specification without code:
- •
Analyze resource requirements:
- •Identify fields and types
- •Determine relationships
- •Note business rules
- •
Generate specification:
- •Endpoint definitions
- •Request/response schemas
- •Error responses
- •Authentication requirements
- •
Output OpenAPI spec or design document
Scaffold (/api scaffold <resource>)
Generate code for API endpoints:
- •Read
prd/00_technology.mdfor framework patterns - •Create route handler
- •Create request/response models
- •Create service layer
- •Create basic tests
Document (/api document)
Generate API documentation:
- •Scan existing endpoints
- •Generate OpenAPI/Swagger spec
- •Create markdown documentation
Validate (/api validate)
Check API against best practices:
- •Check naming conventions
- •Verify HTTP methods used correctly
- •Check response codes
- •Validate schema consistency
REST Design Principles
URL Structure
code
GET /resources # List all GET /resources/:id # Get one POST /resources # Create PATCH /resources/:id # Partial update PUT /resources/:id # Full replace DELETE /resources/:id # Delete # Nested resources GET /users/:id/orders # User's orders POST /users/:id/orders # Create order for user # Actions (when CRUD doesn't fit) POST /orders/:id/cancel # Cancel order POST /users/:id/verify # Verify user
Naming Conventions
- •Use plural nouns for resources:
/usersnot/user - •Use kebab-case for multi-word:
/order-items - •Use lowercase:
/usersnot/Users - •Avoid verbs in URLs (use HTTP methods)
HTTP Status Codes
| Code | Meaning | When to Use |
|---|---|---|
| 200 | OK | Successful GET, PATCH, PUT |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Validation error |
| 401 | Unauthorized | Missing/invalid auth |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 409 | Conflict | Duplicate resource |
| 422 | Unprocessable | Business rule violation |
| 500 | Server Error | Unexpected error |
Response Format
json
// Success (single resource)
{
"data": {
"id": "123",
"type": "user",
"attributes": { ... }
}
}
// Success (collection)
{
"data": [ ... ],
"meta": {
"total": 100,
"page": 1,
"per_page": 20
}
}
// Error
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid email format",
"details": [
{ "field": "email", "message": "Must be valid email" }
]
}
}
API Specification Template
yaml
openapi: 3.0.3
info:
title: Resource API
version: 1.0.0
paths:
/resources:
get:
summary: List resources
parameters:
- name: page
in: query
schema:
type: integer
default: 1
- name: limit
in: query
schema:
type: integer
default: 20
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/ResourceList'
post:
summary: Create resource
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateResource'
responses:
'201':
description: Created
'400':
description: Validation error
/resources/{id}:
get:
summary: Get resource
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
'200':
description: Success
'404':
description: Not found
Security Considerations
- • Authentication required on protected endpoints
- • Authorization checks for resource access
- • Input validation on all endpoints
- • Rate limiting configured
- • Sensitive data not exposed in responses
- • Audit logging for mutations
Example Output
code
$ /api design orders --type rest Designing REST API for: orders Resource Analysis: - Primary entity: Order - Related: User (owner), Items (children), Payment - Operations: CRUD + cancel, refund API Specification: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 Endpoints ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ GET /orders List orders (with filters) GET /orders/:id Get order details POST /orders Create new order PATCH /orders/:id Update order DELETE /orders/:id Delete order (soft delete) POST /orders/:id/cancel Cancel order POST /orders/:id/refund Request refund GET /orders/:id/items List order items POST /orders/:id/items Add item to order ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📝 Schemas ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Order: id: string (uuid) user_id: string (uuid) status: enum [draft, pending, confirmed, shipped, delivered, cancelled] total: number (decimal) currency: string (ISO 4217) items: OrderItem[] created_at: datetime updated_at: datetime CreateOrder: items: CreateOrderItem[] (required, min: 1) shipping_address_id: string (required) payment_method_id: string (required) OrderItem: id: string product_id: string quantity: integer (min: 1) unit_price: number total: number ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔒 Security ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ - All endpoints require authentication - Users can only access their own orders - Admin role can access all orders - Cancel/refund have time-based restrictions Generated: openapi/orders.yaml Next steps: 1. Review specification 2. Run `/api scaffold orders` to generate code 3. Run `/api document` to generate docs