api-design

# API Design Skill

**Bonded to:** `api-development-agent`

---

## Quick Start

```bash
# Invoke api-design skill
"Design a REST API for user management with authentication"
"Implement JWT authentication for my FastAPI app"
"Generate OpenAPI documentation for my endpoints"
```

---

## Instructions

1. **Analyze Requirements**: Understand client needs and data flow
2. **Choose Paradigm**: Select REST, GraphQL, or gRPC
3. **Design Endpoints**: Create resource-oriented API structure
4. **Implement Security**: Add authentication and authorization
5. **Document API**: Generate OpenAPI specification

---

## API Paradigm Selection

| Paradigm | Best For | Performance | Complexity |
|----------|----------|-------------|------------|
| REST | Public APIs, CRUD, simple | Good | Low |
| GraphQL | Complex data, mobile clients | Good | Medium |
| gRPC | Internal services, real-time | Excellent | Medium |
| WebSocket | Bi-directional real-time | Excellent | Medium |

---

## Decision Tree

```
Client type?
    │
    ├─→ Public/Third-party → REST
    │
    ├─→ Mobile with complex data → GraphQL
    │
    ├─→ Internal microservices
    │     ├─→ High performance needed → gRPC
    │     └─→ Standard HTTP preferred → REST
    │
    └─→ Real-time bi-directional → WebSocket
```

---

## Examples

### Example 1: REST API Design
```yaml
# OpenAPI 3.1 Specification
openapi: 3.1.0
info:
  title: User Management API
  version: 1.0.0

paths:
  /api/v1/users:
    post:
      summary: Create user
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: User created
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
      responses:
        '200':
          description: User list

  /api/v1/users/{id}:
    get:
      summary: Get user by ID
    put: