afrexai-api-architect

What this skill does

# API Architect — Full Lifecycle API Development

Design, build, test, document, secure, and monitor production-grade APIs. Not just curl commands — a complete engineering methodology.

## When to Use

- Designing a new API (REST, GraphQL, or gRPC)
- Reviewing an existing API for quality, consistency, or security
- Generating or validating OpenAPI/Swagger specs
- Building comprehensive test suites (unit, integration, contract, load)
- Debugging production API issues
- Planning API versioning and deprecation
- Setting up monitoring, rate limiting, and error handling

---

## Phase 1: API Design

### Design-First Approach

Always design before coding. The spec IS the contract.

#### Resource Modeling

Map your domain to resources using this template:

```yaml
# api-design.yaml
service: order-management
base_path: /api/v1
resources:
  - name: orders
    path: /orders
    description: Customer purchase orders
    identifier: order_id (UUID)
    parent: null
    operations: [list, create, get, update, cancel]
    sub_resources:
      - name: line_items
        path: /orders/{order_id}/items
        operations: [list, add, update, remove]
      - name: payments
        path: /orders/{order_id}/payments
        operations: [list, create, get, refund]
    states: [draft, confirmed, processing, shipped, delivered, cancelled]
    transitions:
      - from: draft → to: confirmed (action: confirm)
      - from: confirmed → to: processing (action: process)
      - from: processing → to: shipped (action: ship)
      - from: shipped → to: delivered (action: deliver)
      - from: [draft, confirmed] → to: cancelled (action: cancel)
```

#### Naming Conventions Checklist

| Rule | Good | Bad |
|------|------|-----|
| Plural nouns for collections | `/users` | `/user`, `/getUsers` |
| Kebab-case for multi-word | `/line-items` | `/lineItems`, `/line_items` |
| No verbs in URLs | `POST /orders` | `/createOrder` |
| Nest for ownership | `/users/123/orders` | `/orders?user=123` (for primary relationship) |
| Max 3 levels deep | `/users/123/orders` | `/users/123/orders/456/items/789/options` |
| Filter via query params | `/orders?status=active` | `/active-orders` |
| Actions as sub-resource | `POST /orders/123/cancel` | `PATCH /orders/123 {cancelled:true}` |

#### HTTP Methods — Decision Matrix

```
Need to...                          → Method   Idempotent?  Safe?
Get a resource or collection        → GET      Yes          Yes
Create a new resource               → POST     No           No
Full replace of a resource          → PUT      Yes          No
Partial update of a resource        → PATCH    No*          No
Remove a resource                   → DELETE   Yes          No
Check if resource exists            → HEAD     Yes          Yes
List allowed methods                → OPTIONS  Yes          Yes

* PATCH can be idempotent if using JSON Merge Patch
```

#### Status Code Decision Tree

```
Success?
├── Created something new? → 201 Created (Location header)
├── Accepted for async processing? → 202 Accepted (include status URL)
├── No body to return? → 204 No Content
└── Returning data? → 200 OK

Client error?
├── Malformed request syntax? → 400 Bad Request
├── No/invalid credentials? → 401 Unauthorized
├── Valid credentials but insufficient permissions? → 403 Forbidden
├── Resource doesn't exist? → 404 Not Found
├── Method not allowed on resource? → 405 Method Not Allowed
├── Conflict with current state? → 409 Conflict
├── Resource permanently gone? → 410 Gone
├── Validation failed? → 422 Unprocessable Entity
├── Too many requests? → 429 Too Many Requests (Retry-After header)
└── Precondition failed (etag mismatch)? → 412 Precondition Failed

Server error?
├── Unexpected failure? → 500 Internal Server Error
├── Upstream dependency failed? → 502 Bad Gateway
├── Temporarily overloaded? → 503 Service Unavailable (Retry-After)
└── Upstream timeout? → 504 Gateway Timeout
```

### Request/Response Design

#### Standard Response Envelope

```json
// Success (single resource)
{
  "data": { "id": "ord_abc123", "status": "confirmed", ... },
  "meta": { "request_id": "req_xyz789" }
}

// Success (collection)
{
  "data": [ ... ],
  "meta": { "request_id": "req_xyz789" },
  "pagination": {
    "total": 142,
    "page": 2,
    "per_page": 20,
    "total_pages": 8,
    "next": "/api/v1/orders?page=3&per_page=20",
    "prev": "/api/v1/orders?page=1&per_page=20"
  }
}

// Error
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Must be a valid email address", "code": "INVALID_FORMAT" },
      { "field": "age", "message": "Must be at least 18", "code": "MIN_VALUE", "min": 18 }
    ]
  },
  "meta": { "request_id": "req_xyz789" }
}
```

#### Pagination Patterns — When to Use Which

| Pattern | Use When | Pros | Cons |
|---------|----------|------|------|
| **Offset** `?page=2&per_page=20` | Simple UI pagination, small datasets | Easy to implement, page jumping | Drift on inserts, slow on large offsets |
| **Cursor** `?after=eyJ...&limit=20` | Infinite scroll, real-time feeds, large datasets | Consistent, performant | No page jumping, opaque cursors |
| **Keyset** `?created_after=2024-01-01&limit=20` | Time-series data, logs | Fast, transparent | Requires sortable field, no count |

#### Filtering, Sorting, Field Selection

```
# Filtering
GET /orders?status=active&created_after=2024-01-01&total_min=100

# Sorting (prefix - for descending)
GET /orders?sort=-created_at,total

# Field selection (reduce payload)
GET /orders?fields=id,status,total,customer.name

# Search
GET /products?q=wireless+headphones

# Combined
GET /orders?status=active&sort=-created_at&fields=id,status,total&page=1&per_page=10
```

---

## Phase 2: OpenAPI Specification

### Generate OpenAPI 3.1 Spec

For each resource in your design, generate a complete spec:

```yaml
openapi: 3.1.0
info:
  title: Order Management API
  version: 1.0.0
  description: |
    Order lifecycle management.
    
    ## Authentication
    All endpoints require Bearer token authentication.
    
    ## Rate Limits
    - Standard: 100 req/min
    - Bulk operations: 10 req/min
  contact:
    name: API Support
    email: [email protected]
  license:
    name: MIT
servers:
  - url: https://api.example.com/v1
    description: Production
  - url: https://staging-api.example.com/v1
    description: Staging

paths:
  /orders:
    get:
      operationId: listOrders
      summary: List orders
      tags: [Orders]
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/PerPageParam'
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/OrderStatus'
        - name: created_after
          in: query
          schema:
            type: string
            format: date-time
      responses:
        '200':
          description: Order list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

    post:
      operationId: createOrder
      summary: Create an order
      tags: [Orders]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            examples:
              basic:
                summary: Basic order
                value:
                  customer_id: "cust_abc"
                  items:
                    - product_id: "prod_xyz"
                      quantity: 2
      responses:
        '201':
          description: Order created
          headers:
            Location:
              schema:
                type: string
              description: URL of created order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderRespons