Api Designer K1lgor

---
name: api-designer
description: Use this when designing APIs (REST or GraphQL), defining routes, request/response schemas, or writing OpenAPI/Swagger specs.
---

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