afrexai-api-architect

name	afrexai-api-architect
description	Design, build, test, document, and secure production-grade APIs. Covers the full lifecycle from schema design through deployment, monitoring, and versioning. Use when designing new APIs, reviewing existing ones, generating OpenAPI specs, building test suites, or debugging production issues.

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:

# 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

// 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" 
     
  




   
     
     
     
             
               
    
  
      

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:

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: [e-mail]
  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 
       []
      
          
          
          
           
          
             
          
           
          
             
             
      
        
            
          
            
              
                 
        
           

    
       
         
       []
      
         
        
          
            
               
            
              
                  
                
                   
                  
                      
                       
      
        
            
          
            
              
                 
                  
          
            
              
                 
        
           


  
    
       
       
       

  
    
       
       
       {  ,  ,   }
    
       
       
       {  ,  ,  ,   }

  
    
          
      
        
          
             
    
         
      
        
          
             


    []

Spec Quality Checklist (score each 0-2)

#	Check	Score
1	Every endpoint has operationId	/2
2	All parameters documented with types + constraints	/2
3	Request bodies have examples	/2
4	All error responses documented (400, 401, 403, 404, 422, 429, 500)	/2
5	Shared schemas use $ref (DRY)	/2
6	Pagination parameters standardized	/2
7	Security scheme defined + applied globally	/2
8	Description includes auth, rate limits, versioning info	/2
9	Response headers documented (Location, Retry-After, ETag)	/2
10	Enums used for fixed value sets	/2

Score: ___/20 (Target: 16+)

---

Phase 3: Implementation Patterns

Request Validation Layer

Every endpoint MUST validate before processing:

Validation Order:
1. Content-Type header (reject non-JSON early)
2. Authentication (401 before wasting cycles)
3. Authorization (403 - does this user have access?)
4. Path parameters (404 - does the resource exist?)
5. Query parameters (400 - valid types/ranges?)
6. Request body schema (422 - valid structure?)
7. Business rules (422 - valid state transition?)

Error Handling — Standard Error Codes

Define a consistent error code enum for your API:

# Authentication & Authorization
AUTH_REQUIRED          — No credentials provided
AUTH_INVALID           — Invalid/expired credentials
AUTH_INSUFFICIENT      — Valid credentials, wrong permissions
AUTH_RATE_LIMITED       — Too many auth attempts

# Validation
VALIDATION_FAILED      — Generic validation error (see details array)
INVALID_FORMAT         — Field format wrong (email, UUID, etc.)
REQUIRED_FIELD         — Required field missing
OUT_OF_RANGE           — Value outside allowed range
INVALID_ENUM           — Value not in allowed set

# Resource
NOT_FOUND              — Resource doesn't exist
ALREADY_EXISTS         — Duplicate (unique constraint)
CONFLICT               — State conflict (e.g., already cancelled)
GONE                   — Resource permanently deleted

# Business Logic
INSUFFICIENT_FUNDS     — Payment-related
QUOTA_EXCEEDED         — Usage limit reached
FEATURE_DISABLED       — Feature flag off
DEPENDENCY_FAILED      — Upstream service error

# System
INTERNAL_ERROR         — Unexpected server error
SERVICE_UNAVAILABLE    — Temporarily down
TIMEOUT                — Request took too long

Idempotency

For non-idempotent operations (POST), require an idempotency key:

Request:
POST /orders
Idempotency-Key: ord_req_abc123

Server behavior:
1. Check if Idempotency-Key was seen before
2. If yes → return cached response (same status, same body)
3. If no → process request, cache response for 24h
4. Key format: client-generated UUID or meaningful string

Rate Limiting

Standard headers to include:

X-RateLimit-Limit: 100          # Max requests per window
X-RateLimit-Remaining: 67       # Remaining in current window
X-RateLimit-Reset: 1706886400   # Unix timestamp when window resets
Retry-After: 30                 # Seconds to wait (on 429)

Rate limit tiers:

Tier	Limit	Window	Use Case
Standard	100/min	Sliding	Normal API calls
Bulk	10/min	Sliding	Batch operations
Search	30/min	Sliding	Full-text search
Auth	5/min	Fixed	Login attempts
Webhook	1000/min	Sliding	Incoming webhooks

---

Phase 4: Testing Strategy

Test Pyramid for APIs

        /  E2E  \          — 5-10 critical user flows
       / Contract \        — Schema validation, backward compat
      / Integration \      — Database, external services, auth
     /    Unit Tests  \    — Business logic, validation, transforms
    ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾

Test Checklist Per Endpoint

For EVERY endpoint, test these scenarios:

endpoint: POST /orders
tests:
  happy_path:
    - Creates order with valid data → 201
    - Returns created resource with ID
    - Location header points to new resource
    - Timestamps are set (created_at, updated_at)
  
  validation:
    - Missing required fields → 422 with field-level errors
    - Invalid field types (string where int expected) → 422
    - Empty body → 400
    - Invalid   
               
              
  
  
        
        
        
          
  
  
          
              
          
  
  
             
              
          
           
             
             
              
  
  
         
             
        

curl Testing Recipes

# === Setup ===
BASE="https://api.example.com/v1"
TOKEN="your_bearer_token"
alias api='curl -s -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json"'

# === CRUD Lifecycle Test ===
# Create
ORDER=$(api -X POST "$BASE/orders" -d '{"customer_id":"cust_1","items":[{"product_id":"prod_1","qty":2}]}')
ORDER_ID=$(echo "$ORDER" | jq -r '.data.id')
echo "Created: $ORDER_ID"

# Read
api "$BASE/orders/$ORDER_ID" | jq .

# Update
api -X PATCH "$BASE/orders/$ORDER_ID" -d '{"notes":"Rush order"}' | jq .

# List with filters
api "$BASE/orders?status=draft&sort=-created_at&per_page=5" | jq .

# Action (state transition)
api -X POST "$BASE/orders/$ORDER_ID/confirm" | jq .

# Delete
curl -s -o /dev/null -w "%{http_code}" -X DELETE -H "Authorization: Bearer $TOKEN" "$BASE/orders/$ORDER_ID"

# === Error Testing ===
# No auth
curl -s "$BASE/orders" | jq .error

# Invalid body
api -X POST "$BASE/orders" -d '{"invalid": true}' | jq .error


api  | jq .error



curl -s -o /dev/null -w  -H  


 50 | xargs -P10 -I{} curl -s -o /dev/null -w  -H  

Contract Testing

Validate your API hasn't broken backward compatibility:

# contract-tests.yaml
contract:
  name: Order API Contract
  version: 1.0.0
  
  rules:
    # These changes are SAFE (non-breaking)
    safe:
      - Adding new optional fields to responses
      - Adding new endpoints
      - Adding new optional query parameters
      - Adding new enum values (if clients handle unknown)
      - Widening a constraint (min: 5 → min: 1)
    
    # These changes are BREAKING
    breaking:
      - Removing a response field
      - Renaming a response field
          
            
         
           
          
          
    
    
    
             
           
                
         
         

---

Phase 5: Security

Security Checklist (audit every API)

authentication:
  - [ ] All endpoints require auth (except /health, /docs, public webhooks)
  - [ ] Tokens expire (short-lived access + long-lived refresh)
  - [ ] Token rotation supported
  - [ ] Failed auth returns 401 with no info leakage
  - [ ] API keys are hashed in storage (never plain text)

authorization:
  - [ ] Resource-level checks (user can only access their data)
  - [ ] Endpoint-level checks (role-based access)
  - [ ]         
   [ ]    
   [ ]    


   [ ]       
   [ ]      
   [ ]   
   [ ]   
   [ ]       
   [ ]      


   [ ]         
   [ ]      
   [ ]          
   [ ]    


   [ ]      
   [ ]   
   [ ]   
   [ ]       
  

   [ ]  
   [ ]  
   [ ]  
   [ ]    
   [ ]     

CORS Configuration

# Restrictive (recommended)
cors:
  origins:
    - https://app.example.com
    - https://admin.example.com
  methods: [GET, POST, PUT, PATCH, DELETE]
  headers: [Authorization, Content-Type, X-Request-ID]
  credentials: true
  max_age: 3600

# Common mistakes to avoid:
# ❌ Access-Control-Allow-Origin: *  (with credentials)
# ❌ Reflecting Origin header without validation
# ❌ Allowing all methods/headers

---

Phase 6: Versioning & Deprecation

Versioning Strategy Decision

Strategy	Example	Pros	Cons	Use When
URL path	/v1/orders	Explicit, easy routing	URL pollution	Public APIs, multiple major versions
Header	API-Version: 2024-01	Clean URLs	Hidden, harder to test	Internal APIs
Query param	?version=2	Easy to test	Pollutes params	Quick prototypes
Date-based	2024-01-15	Clear timeline	Many versions	Stripe-style APIs

Recommended: URL path for major versions, header for minor variations.

Deprecation Playbook

Timeline:
1. T+0: Announce deprecation (docs, changelog, email)
2. T+0: Add Deprecation + Sunset headers to old endpoints
3. T+30d: Log warnings for old endpoint usage
4. T+60d: Email heavy users of old endpoint directly
5. T+90d: Return 299 warning header
6. T+180d: Shut down old endpoint (410 Gone)

Headers:
Deprecation: true
Sunset: Sat, 01 Jun 2025 00:00:00 GMT
Link: <https://api.example.com/v2/orders>; rel="successor-version"

Migration Guide Template

# Migrating from v1 to v2

## Breaking Changes
1. `user.name` split into `user.first_name` + `user.last_name`
2. Pagination changed from offset to cursor-based
3. Error format updated (see new schema)

## Step-by-Step Migration
1. Update your client SDK to v2 (`npm install @example/sdk@2`)
2. Update response parsing for split name fields
3. Replace `?page=N` with `?after=cursor` pagination
4. Update error handling for new error format

## Compatibility Mode
Set `X-Compat-Mode: v1` header to get v1-style responses from v2 endpoints.
Available until 2025-06-01.

---

Phase 7: Monitoring & Observability

Key Metrics Dashboard

availability:
  - Uptime percentage (target: 99.9% = 8.7h downtime/year)
  - Health check status (/health endpoint)
  - Error rate (5xx / total requests)

performance:
  - p50 latency (target: < 100ms)
  - p95 latency (target: < 500ms)
  - p99 latency (target: < 1000ms)
  - Throughput (requests/second)
  - Time to first byte (TTFB)

business:
  - Requests per endpoint (usage patterns)
  - Unique API consumers/day
  - Error rate  
     
    


      
     
     
      

Structured Logging

Every request should log:

{
  "timestamp": "2024-01-15T10:30:00.000Z",
  "level": "info",
  "request_id": "req_abc123",
  "method": "POST",
  "path": "/api/v1/orders",
  "status": 201,
  "duration_ms": 45,
  "user_id": "usr_xyz",
  "ip": "203.0.113.1",
  "user_agent": "MyApp/2.0",
  "request_size": 256,
  "response_size": 1024
}

Health Check Endpoint

// GET /health — for load balancers (simple)
{ "status": "ok" }

// GET /health/detailed — for monitoring (authenticated)
{
  "status": "degraded",
  "version": "1.5.2",
  "uptime_seconds": 86400,
  "checks": {
    "database": { "status": "ok", "latency_ms": 5 },
    "redis": { "status": "ok", "latency_ms": 2 },
    "external_payment_api": { "status": "degraded", "latency_ms": 2500,   
          
  

---

Phase 8: API Review Scoring

When reviewing an existing API, score across these dimensions:

API Quality Rubric (0-100)

Dimension	Weight	Criteria	Score
Design Consistency	20%	Naming conventions, HTTP methods, status codes, URL structure	/20
Documentation	15%	OpenAPI spec, examples, error docs, changelog	/15
Error Handling	15%	Consistent format, helpful messages, proper codes, no leakage	/15
Security	20%	Auth, input validation, CORS, headers, no IDOR	/20
Performance	15%	Latency targets met, pagination, caching headers, N+1 prevented	/15
Developer Experience	15%	SDK quality, sandbox available, onboarding time, rate limit clarity	/15

Score: ___/100

Rating	Score	Action
🟢 Excellent	85-100	Minor improvements only
🟡 Good	70-84	Address gaps before next major release
🟠 Needs Work	50-69	Prioritize improvements, create tech debt tickets
🔴 Critical	<50	Stop feature work, fix fundamentals first

Review Output Template

## API Review: [Service Name]

**Date:** YYYY-MM-DD
**Reviewer:** [Agent]
**Score:** XX/100 (Rating)

### Summary
[2-3 sentence overview of API quality]

### Scores by Dimension
- Design Consistency: X/20 — [key finding]
- Documentation: X/15 — [key finding]
- Error Handling: X/15 — [key finding]
- Security: X/20 — [key finding]
- Performance: X/15 — [key finding]
- Developer Experience: X/15 — [key finding]

### Critical Issues (fix immediately)
1. [Issue + recommendation]

### High Priority (fix this sprint)
1. [Issue + recommendation]

### Nice to Have (backlog)
1. [Issue + recommendation]

### Positive Highlights
- [What's working well]

---

GraphQL-Specific Guidance

Schema Design Principles

# Good: clear types, nullable where appropriate, connections for lists
type Order {
  id: ID!
  status: OrderStatus!
  customer: Customer!
  items(first: Int, after: String): ItemConnection!
  total: Money!
  createdAt: DateTime!
  updatedAt: DateTime!
}

type Money {
  amount: Int!       # cents, not dollars (avoid float)
  currency: Currency!
}

enum OrderStatus {
  DRAFT
  CONFIRMED
  PROCESSING
  SHIPPED
  DELIVERED
  CANCELLED
}

# Mutations return the modified resource + errors
type CreateOrderPayload {
  order: Order
  errors: [UserError!]


 UserError 
   String
   String
   ErrorCode

GraphQL Anti-Patterns

Anti-Pattern	Problem	Fix
No depth limit	Query bombs	Limit depth to 5-7 levels
No complexity limit	Expensive queries	Assign cost per field, cap at 1000
N+1 queries	Performance death	Use DataLoader pattern
No persisted queries	Security risk	Whitelist queries in production
Exposing internal IDs	Leaks implementation	Use opaque global IDs
No pagination	Memory explosion	Use Relay Connection spec

---

Edge Cases & Gotchas

Timezone Handling

• Always store and return UTC (ISO 8601: 2024-01-15T10:30:00Z)
• Accept timezone in input, convert to UTC immediately
• Never use local server time

Large Payloads

• Set Content-Length limits (e.g., 1MB default, 10MB for uploads)
• Use streaming for file uploads (multipart/form-data)
• Compress responses (Accept-Encoding: gzip)
• For very large exports → return 202 + poll status endpoint

Eventual Consistency

• If using async processing, always return 202 + status URL
• Include estimated completion time when possible
• Client should poll with exponential backoff

Concurrent Updates

• Use ETags for optimistic concurrency:
  • GET returns ETag: "v1" header
  • PUT/PATCH sends If-Match: "v1" header
  • Server returns 412 if resource changed since

Webhook Design

• Include event type, timestamp, and full resource in payload
• Sign payloads (HMAC-SHA256)
• Expect retries (make handlers idempotent)
• Return 200 quickly, process async
• Include webhook ID for deduplication

---

Quick Commands

Request	Action
"Design an API for [domain]"	Run Phase 1 resource modeling + naming
"Generate OpenAPI spec"	Run Phase 2 with full components
"Review this API"	Run Phase 8 scoring rubric
"Write tests for [endpoint]"	Run Phase 4 endpoint checklist
"Security audit this API"	Run Phase 5 security checklist
"How should I version this?"	Run Phase 6 decision matrix
"Debug this API issue"	Check Phase 7 logging + health patterns
"Design GraphQL schema for [domain]"	Run GraphQL section