API Architect
Expert API designer specializing in REST, GraphQL, gRPC, and WebSocket architectures.
Activation Triggers
Activate on: "API design", "REST API", "GraphQL schema", "gRPC service", "OpenAPI", "Swagger", "API versioning", "endpoint design", "rate limiting", "OAuth flow", "API gateway"
NOT for: Database schema →
| Frontend consumption →
| Deployment →
Quick Start
- Define API contract first (API-first design)
- Choose paradigm: REST for CRUD, GraphQL for flexible queries, gRPC for internal services
- Write the spec: OpenAPI for REST, SDL for GraphQL, .proto for gRPC
- Design error responses with consistent structure
- Plan versioning before your first release
Core Capabilities
| Domain | Technologies |
|---|
| REST | OpenAPI 3.1, HATEOAS, Pagination |
| GraphQL | SDL, Relay, DataLoader, Federation |
| gRPC | Protocol Buffers, Streaming patterns |
| Security | OAuth 2.0, JWT, API Keys, RBAC |
| DX | Swagger UI, SDK generation, Sandboxes |
Architecture Patterns
API-First Development
Design Contract → Generate Stubs → Implement → Test Against Spec
Response Envelope
yaml
success: { data: <resource>, meta: { page, total } }
error: { error: { code, message, details: [{ field, issue }] } }
Versioning Options
- URL: (most explicit)
- Header:
Accept: application/vnd.api+json;version=1
- Query:
Reference Files
Full working examples in
:
| File | Description | Lines |
|---|
| Complete OpenAPI 3.1 spec | 162 |
| GraphQL with Relay connections | 111 |
| Protocol Buffer, all streaming | 95 |
| Tier-based rate limit config | 85 |
| Auth, CORS, security headers | 130 |
Anti-Patterns (AVOID These)
1. Verb-Based URLs
Symptom:
,
,
Fix: Use nouns (
,
), let HTTP methods convey action
2. Inconsistent Response Envelopes
Symptom:
sometimes, raw arrays other times
Fix: Always use consistent envelope structure
3. Breaking Changes Without Versioning
Symptom: Removing fields, changing types without warning
Fix: Semantic versioning, deprecation headers, sunset periods
4. N+1 in GraphQL
Symptom: Resolver queries database per item in list
Fix: DataLoader pattern for batching,
for large payloads
5. Over-fetching REST Endpoints
Symptom:
returns 50 fields when clients need 3
Fix: Sparse fieldsets (
) or GraphQL
6. Missing Pagination
Symptom: List endpoints return all records
Fix: Default limits, cursor-based pagination,
indicator
7. No Idempotency Keys
Symptom: Duplicate POST requests create duplicate resources
Fix: Accept
header, return cached response
8. Leaky Internal Errors
Symptom: Stack traces, SQL errors exposed in 500 responses
Fix: Generic error messages in production, request IDs for debugging
9. Missing CORS Configuration
Symptom: Browser clients blocked with CORS errors
Fix: Configure allowed origins, methods, headers explicitly
10. No Rate Limiting
Symptom: API vulnerable to abuse, no usage visibility
Fix: Implement limits per tier, return
headers
Validation Script
Run
./scripts/validate-api-spec.sh
to check:
- OpenAPI specs for versions, security schemes, operationIds
- GraphQL schemas for Query types, pagination, error handling
- Protocol Buffers for syntax, packages, field numbers
- Common issues like hardcoded URLs, missing versioning
Quality Checklist
[ ] All endpoints use nouns, not verbs
[ ] Consistent response envelope structure
[ ] Error responses include codes and actionable messages
[ ] Pagination on all list endpoints
[ ] Authentication/authorization documented
[ ] Rate limit headers defined
[ ] Versioning strategy documented
[ ] CORS configured for known origins
[ ] Idempotency keys for mutating operations
[ ] OpenAPI spec validates without errors
[ ] SDK generation tested
[ ] Examples for all request/response types
Output Artifacts
- OpenAPI Specifications - Complete API contracts
- GraphQL Schemas - Type definitions with connections
- Protocol Buffers - gRPC service definitions
- API Documentation - Developer guides
- SDK Examples - Client code samples
- Postman Collections - API test suites
Tools Available
- , , - File operations for specs
- - OpenAPI linting, code generation
Bash(openapi-generator:*)