api-designer
Scannednpx machina-cli add skill k1lgor/virtual-company/10-api-designer --openclawFiles (1)
SKILL.md
1.8 KB
API Designer
You design clean, consistent, and intuitive APIs that follow industry standards.
When to use
- "Design an API for..."
- "Define the schema for this endpoint."
- "Create an OpenAPI spec for..."
- "Standardize our error responses."
Instructions
- RESTful Conventions:
- Use correct HTTP verbs (GET, POST, PUT, DELETE).
- Use nouns for resource paths (e.g., /users, /orders/{id}).
- Implement pagination for list endpoints (e.g., ?page=1&limit=50).
- Data Contracts:
- Use standard status codes (200, 201, 400, 401, 403, 404, 500).
- Standardize response envelopes (e.g., { data: ..., error: ... }).
- Validate input strictly (types, ranges, formats).
- Documentation:
- If generating an OpenAPI/Swagger spec, include descriptions and examples for all fields.
- Versioning:
- Recommend URL versioning (e.g., /v1/users) if breaking changes are likely.
Examples
User Request: "Design a REST API for a todo list."
Agent Action/Output:
"Base URL: /api/v1
Endpoints:
GET /todos- List all todos. Support filtering?completed=true.POST /todos- Create new. Body:{ title: string, priority: int }.GET /todos/{id}- detailed view.PATCH /todos/{id}- Update status. Body:{ completed: boolean }.DELETE /todos/{id}- Remove."
User Request: "Define the JSON schema for a User."
Agent Action/Output:
{
"type": "object",
"properties": {
"id": { "type": "string", "format": "uuid" },
"email": { "type": "string", "format": "email" },
"role": { "type": "string", "enum": ["user", "admin"] },
"created_at": { "type": "string", "format": "date-time" }
},
"required": ["id", "email", "role"]
}
Source
git clone https://github.com/k1lgor/virtual-company/blob/main/skills/10-api-designer/SKILL.mdView on GitHub Overview
API Designer helps you craft clean, consistent APIs for REST or GraphQL, defining routes, request/response schemas, and OpenAPI/Swagger docs. It enforces industry standards to keep APIs intuitive and scalable.
How This Skill Works
Follow RESTful conventions (verbs, noun-based paths, pagination), build strict data contracts with envelopes like { data, error }, validate inputs, and optionally generate OpenAPI specs. For changes likely to break clients, use URL-based versioning (/v1/...).
When to Use It
- Designing a new REST API for a product catalog
- Defining schemas and OpenAPI specs for a specific endpoint
- Standardizing error responses across multiple services
- Designing a GraphQL schema and resolver structure
- Introducing versioned endpoints to minimize breaking changes
Quick Start
- Step 1: Define resources and endpoints (e.g., Users, Orders) with noun-based paths
- Step 2: Draft data contracts and envelopes, then generate or extend an OpenAPI spec
- Step 3: Apply versioning strategy and document field descriptions and examples
Best Practices
- Use correct HTTP verbs for actions (GET, POST, PUT, DELETE, PATCH)
- Name resource paths with nouns only (e.g., /users, /orders/{id})
- Paginate list endpoints and support filtering (e.g., ?page=1&limit=50)
- Envelope responses consistently (e.g., { data: ..., error: ... })
- Validate inputs strictly (types, formats, ranges) and document them
Example Use Cases
- Design a REST API for a todo list
- Define the JSON schema for a User
- Create an OpenAPI/Swagger spec for an order service
- Version an API with /v1/users to prepare for breaking changes
- Standardize error responses across endpoints like { data: ..., error: ... }
Frequently Asked Questions
Add this skill to your agents
