afrexai-api-architect

# 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: api@example.com 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/OrderResponse' '422': $ref: '#/components/responses/ValidationError' components: securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT parameters: PageParam: name: page in: query schema: { type: integer, minimum: 1, default: 1 } PerPageParam: name: per_page in: query schema: { type: integer, minimum: 1, maximum: 100, default: 20 } responses: Unauthorized: description: Missing or invalid authentication content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ValidationError: description: Request validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - BearerAuth: [] ``` ### 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: ```yaml 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 Content-Type → 415 - Extra unknown fields → ignored or 422 (pick one, be consistent) - Boundary values (min/max length, 0, negative, empty string vs null) authentication: - No token → 401 - Expired token → 401 - Invalid token → 401 - Valid token, wrong scope → 403 authorization: - User accessing own resource → 200 - User accessing other's resource → 403 or 404 (security choice) - Admin accessing any resource → 200 edge_cases: - Duplicate creation (same idempotency key) → same 201 response - Concurrent creation race condition → one wins, one gets 409 - Resource at max relationships → 422 - Unicode in text fields → handled correctly - Very long strings → 422 with max length error - SQL injection in params → no effect (parameterized queries) - XSS in text fields → stored safely, escaped on output performance: - Response time < 200ms (p95) - List endpoint with 10K records → paginated, < 500ms - Bulk operation timeout handling ``` ### curl Testing Recipes ```bash # === Setup === BASE="https://api.example.com/v1" TOKEN="your_bearer_token"