Some_claude_skills api-architect

'Expert API designer for REST, GraphQL, gRPC architectures. Activate on: API design, REST API, GraphQL schema, gRPC service, OpenAPI, Swagger, API versioning, endpoint design, rate limiting,

install

source · Clone the upstream repo

git clone https://github.com/curiositech/some_claude_skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/curiositech/some_claude_skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/api-architect" ~/.claude/skills/erichowens-some-claude-skills-api-architect && rm -rf "$T"

manifest: .claude/skills/api-architect/SKILL.md

source content

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

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

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/

File	Description	Lines
`openapi-spec.yaml`	Complete OpenAPI 3.1 spec	162
`graphql-schema.graphql`	GraphQL with Relay connections	111
`grpc-service.proto`	Protocol Buffer, all streaming	95
`rate-limiting.yaml`	Tier-based rate limit config	85
`api-security.yaml`	Auth, CORS, security headers	130

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

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

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