# API Designer

> Use this when designing APIs (REST or GraphQL), defining routes, request/response schemas, or writing OpenAPI/Swagger specs.

- Skill: `diegosouzapw/api-designer-3` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/api-designer-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/api-designer-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/diegosouzapw/api-designer-3

---


# 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

1. 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).
2. 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).
3. Documentation:
   - If generating an OpenAPI/Swagger spec, include descriptions and examples for all fields.
4. 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**:

1. `GET /todos` - List all todos. Support filtering `?completed=true`.
2. `POST /todos` - Create new. Body: `{ title: string, priority: int }`.
3. `GET /todos/{id}` - detailed view.
4. `PATCH /todos/{id}` - Update status. Body: `{ completed: boolean }`.
5. `DELETE /todos/{id}` - Remove."

User Request: "Define the JSON schema for a User."

Agent Action/Output:

```json
{
  "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"]
}
```