🇺🇸English

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 → data-pipeline-engineer | Frontend consumption → web-design-expert | Deployment → devops-automator

Quick Start

1. Define API contract first (API-first design)
2. Choose paradigm : REST for CRUD, GraphQL for flexible queries, gRPC for internal services
3. Write the spec : OpenAPI for REST, SDL for GraphQL, .proto for gRPC
4. Design error responses with consistent structure
5. Plan versioning before your first release

Core Capabilities

Architecture Patterns

API-First Development

Design Contract → Generate Stubs → Implement → Test Against Spec

Response Envelope

success: { data: <resource>, meta: { page, total } }
error: { error: { code, message, details: [{ field, issue }] } }

Versioning Options

• URL: /v1/users (most explicit)
• Header: Accept: application/vnd.api+json;version=1
• Query: /users?version=1

Reference Files

Full working examples in ./references/:

Anti-Patterns (AVOID These)

1. Verb-Based URLs

Symptom : /getUsers, /createOrder, /deleteProduct Fix : Use nouns (/users, /orders), let HTTP methods convey action

2. Inconsistent Response Envelopes

Symptom : {data: [...]} 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, @defer for large payloads

5. Over-fetching REST Endpoints

Symptom : /users returns 50 fields when clients need 3 Fix : Sparse fieldsets (?fields=id,name,email) or GraphQL

6. Missing Pagination

Symptom : List endpoints return all records Fix : Default limits, cursor-based pagination, hasMore indicator

7. No Idempotency Keys

Symptom : Duplicate POST requests create duplicate resources Fix : Accept Idempotency-Key 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 X-RateLimit-* 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

1. OpenAPI Specifications - Complete API contracts
2. GraphQL Schemas - Type definitions with connections
3. Protocol Buffers - gRPC service definitions
4. API Documentation - Developer guides
5. SDK Examples - Client code samples
6. Postman Collections - API test suites

Tools Available

• Read, Write, Edit - File operations for specs
• Bash(npm:*, npx:*) - OpenAPI linting, code generation
• Bash(openapi-generator:*) - SDK generation

Weekly Installs

56

Repository

erichowens/some…e_skills

GitHub Stars

78

First Seen

Jan 23, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

codex49

cursor49

opencode48

gemini-cli48

github-copilot45

cline40