faion-api-developer

name	faion-api-developer
description	API development: REST, GraphQL, OpenAPI, versioning, auth, rate limiting.
user-invocable	false
allowed-tools	Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion, TodoWrite, Skill

Entry point: /faion-net — invoke this skill for automatic routing to the appropriate domain.

API Developer Skill

API design and development covering REST, GraphQL, OpenAPI specifications, authentication, and API best practices.

Purpose

Handles API design, documentation, authentication, rate limiting, versioning, and API-specific patterns.

---

Context Discovery

Auto-Investigation

Detect API patterns from project:

Signal	How to Check	What It Tells Us
OpenAPI spec	Glob("**/openapi.yaml") or Glob("**/swagger.*")	API documented
GraphQL schema	Glob("**/*.graphql")	GraphQL API
DRF	Grep("rest_framework", "**/settings.py")	Django REST Framework
FastAPI	Grep("fastapi", "**/requirements.txt")	FastAPI used
Express routes	Grep("app.get|app.post|router", "**/*.js")	Express API
Auth middleware	Grep("jwt|oauth|auth", "**/*.py")	Auth patterns

Read existing patterns:

• Check existing endpoints for conventions
• Read serializers/schemas for data patterns
• Check middleware for auth/rate limiting

Discovery Questions

Q1: API Type

question: "What type of API are you building?"
header: "Type"
multiSelect: false
options:
  - label: "REST API"
    description: "Resource-based HTTP endpoints"
  - label: "GraphQL API"
    description: "Query language, single endpoint"
  - label: "WebSocket/Real-time"
    description: "Bidirectional communication"
  - label: "RPC-style"
    description: "Action-based endpoints"

Routing:

• "REST" → api-rest-design, OpenAPI
• "GraphQL" → graphql-api-design
• "WebSocket" → websocket-design
• "RPC" → REST patterns adapted

Q2: API Consumers

question: "Who will consume this API?"
header: "Consumers"
multiSelect: true
options:
  - label: "Own frontend (SPA/mobile)"
    description: "First-party clients"
  - label: "Third-party developers"
    description: "Public API, need docs"
  - label: "Internal services"
    description: "Microservices communication"
  - label: "Partners (B2B)"
    description: "Specific integrations"

Context impact:

• "Own frontend" → Simpler auth, less versioning
• "Third-party" → Full docs, versioning, rate limits
• "Internal" → Service auth, less public docs
• "Partners" → API keys, dedicated support

Q3: Authentication Needs

question: "How should API authentication work?"
header: "Auth"
multiSelect: false
options:
  - label: "JWT tokens"
    description: "Stateless, self-contained tokens"
  - label: "Session-based"
    description: "Server-side sessions"
  - label: "API keys"
    description: "Simple key-based auth"
  - label: "OAuth 2.0"
    description: "Third-party auth flow"
  - label: "No auth needed"
    description: "Public API"

Q4: Documentation Approach

question: "How should API be documented?"
header: "Docs"
multiSelect: false
options:
  - label: "OpenAPI/Swagger (auto-generated)"
    description: "Generate from code"
  - label: "OpenAPI (design-first)"
    description: "Write spec first, then implement"
  - label: "Markdown docs"
    description: "Manual documentation"
  - label: "GraphQL introspection"
    description: "Self-documenting schema"

---

When to Use

• REST API design and implementation
• GraphQL API design
• OpenAPI/Swagger specifications
• API authentication (OAuth, JWT, API keys)
• API versioning strategies
• API rate limiting and throttling
• API error handling
• API testing
• API gateways
• API monitoring
• WebSocket APIs

Methodologies

Category	Methodology	File
REST APIs
REST API design	RESTful principles, resource design	api-rest-design.md
REST API design alt	REST patterns and best practices	rest-api-design.md
GraphQL
GraphQL API basics	Schema, queries, mutations	api-graphql.md
GraphQL API design	Schema design, resolvers, federation	graphql-api-design.md
GraphQL API alt	GraphQL patterns	graphql-api.md
OpenAPI
OpenAPI spec	OpenAPI 3.x specification	api-openapi-spec.md
OpenAPI specification	Spec writing, code generation	openapi-specification.md
API Patterns
Contract-first API	Schema-first development	api-contract-first.md
Contract-first development	API-first approach	contract-first-development.md
API versioning	Version strategies (URL, header, media type)	api-versioning.md
API error handling	Error codes, error responses	api-error-handling.md
API authentication	OAuth 2.0, JWT, API keys	api-authentication.md
API rate limiting	Rate limiting strategies	api-rate-limiting.md
Rate limiting	Throttling patterns	rate-limiting.md
API gateway patterns	Gateway design, BFF pattern	api-gateway-patterns.md
API monitoring	Metrics, logging, tracing	api-monitoring.md
Testing & Docs
API testing	Integration testing, contract testing	api-testing.md
API documentation	API docs, Swagger UI	api-documentation.md

Tools

• REST: OpenAPI 3.x, Swagger, Postman
• GraphQL: Apollo Server, GraphQL Yoga, Hasura
• Auth: OAuth 2.0, JWT, Passport.js, Auth0
• Testing: Postman, REST Client, Hoppscotch
• Documentation: Swagger UI, Redoc, Stoplight
• Gateways: Kong, Tyk, API Gateway (AWS)

Related Sub-Skills

Sub-skill	Relationship
faion-python-developer	Django REST Framework, FastAPI
faion-javascript-developer	Express, Fastify, GraphQL
faion-backend-developer	API implementation in Go, Java, etc.
faion-testing-developer	API testing strategies

Integration

Invoked by parent skill faion-software-developer for API design and implementation work.

---

Methodology Context & Decision Trees

api-rest-design.md

Required Context:

• API consumers defined (frontend, third-party, internal)
• Data entities/resources modeled
• Authentication requirements known
• Versioning strategy decided

Decision Tree:

Start
├── Resources/entities clear?
│   └── NO → faion-ba-modeling (data-analysis) first
├── Consumers defined?
│   └── NO → faion-product-manager (stakeholder-analysis)
├── Auth requirements?
│   └── NO → See api-authentication.md
└── YES to all → Proceed with REST design

If Missing:

Context	Skill/Methodology
Data model	faion-ba-modeling → data-analysis
Security needs	faion-software-architect → security-architecture
Consumer requirements	faion-product-manager → product-operations

---

graphql-api-design.md

Required Context:

• Data relationships understood (graph structure)
• Query patterns known
• N+1 awareness
• Client requirements (frontend framework)

Decision Tree:

Start
├── Complex relationships?
│   └── NO → Consider REST instead (simpler)
├── Multiple clients with different needs?
│   └── NO → REST may be sufficient
├── Need real-time subscriptions?
│   └── YES → GraphQL with subscriptions
└── Proceed with GraphQL

If Missing:

Context	Skill/Methodology
Data relationships	faion-ba-modeling → data-analysis
Query optimization	faion-backend-systems → database-optimization
Frontend needs	faion-frontend-developer

---

api-authentication.md

Required Context:

• User types (end-user, service, admin)
• Session requirements (stateless vs stateful)
• Third-party auth needs (OAuth providers)
• Security compliance (OWASP, SOC2)

Decision Tree:

Start
├── Third-party login needed?
│   └── YES → OAuth 2.0 / OIDC
├── Service-to-service?
│   └── YES → API keys or mTLS
├── Need stateless?
│   └── YES → JWT tokens
├── Need session management?
│   └── YES → Session-based auth
└── Simple internal API → API keys

If Missing:

Context	Skill/Methodology
Security requirements	faion-software-architect → security-architecture
Compliance needs	faion-devops-engineer → security-compliance
User types	faion-ba-core → stakeholder-analysis

---

api-versioning.md

Required Context:

• API maturity (new vs established)
• Breaking change frequency
• Client update capability
• Deprecation policy

Decision Tree:

Start
├── Public API with external clients?
│   └── YES → URL versioning (/v1/) recommended
├── Internal services only?
│   └── YES → Header versioning or no versioning
├── GraphQL?
│   └── YES → Schema evolution, no versioning needed
└── Frequent breaking changes → Media type versioning

If Missing:

Context	Skill/Methodology
API consumers	faion-product-manager → stakeholder-analysis
Deprecation policy	faion-sdd-planning → spec-writing

---

api-rate-limiting.md

Required Context:

• Traffic patterns known
• Client tiers (free, paid, enterprise)
• Infrastructure capacity
• Burst vs sustained load

Decision Tree:

Start
├── Multi-tenant SaaS?
│   └── YES → Per-tenant rate limits
├── Public API?
│   └── YES → Tiered rate limiting
├── Internal only?
│   └── Consider circuit breakers instead
└── Define limits: requests/minute/hour/day

If Missing:

Context	Skill/Methodology
Traffic analysis	faion-software-architect → performance-architecture
Pricing tiers	faion-product-manager → product-planning
Infrastructure	faion-devops-engineer → infrastructure

---

api-error-handling.md

Required Context:

• Error categories defined
• Client error display requirements
• Logging/monitoring setup
• Localization needs

Decision Tree:

Start
├── Public API?
│   └── YES → RFC 7807 Problem Details
├── Internal API?
│   └── Consistent error schema
├── Need debugging info?
│   └── DEV only, never in production
└── Always: structured errors, proper HTTP codes

If Missing:

Context	Skill/Methodology
Error categories	faion-ba-core → requirements-analysis
Monitoring	faion-software-architect → observability-architecture

---

api-openapi-spec.md

Required Context:

• All endpoints defined
• Request/response schemas
• Auth schemes
• Examples for each endpoint

Decision Tree:

Start
├── Design-first approach?
│   └── YES → Write OpenAPI first, generate code
├── Code-first approach?
│   └── YES → Generate OpenAPI from code
├── Need code generation?
│   └── YES → Ensure strict typing in spec
└── OpenAPI 3.1 recommended (JSON Schema)

If Missing:

Context	Skill/Methodology
Endpoint design	api-rest-design.md
Data schemas	faion-ba-modeling → data-analysis

---

websocket-design.md

Required Context:

• Real-time use case defined
• Message types/events
• Connection lifecycle
• Scale requirements (connections count)

Decision Tree:

Start
├── Need bidirectional?
│   └── NO → Consider SSE instead
├── High frequency updates?
│   └── YES → WebSocket with batching
├── Many concurrent connections?
│   └── YES → Consider dedicated WS server
└── Define: connect, message, disconnect flows

If Missing:

Context	Skill/Methodology
Real-time requirements	faion-ba-core → requirements-analysis
Scale architecture	faion-software-architect → distributed-patterns
Infrastructure	faion-devops-engineer → infrastructure

---

api-gateway-patterns.md

Required Context:

• Number of backend services
• Client types (web, mobile, IoT)
• Cross-cutting concerns (auth, rate limit, logging)
• Traffic patterns

Decision Tree:

Start
├── Single backend service?
│   └── NO → Consider API gateway
├── Multiple client types with different needs?
│   └── YES → BFF pattern (Backend for Frontend)
├── Need aggregation across services?
│   └── YES → Gateway with composition
└── Cross-cutting: auth, rate limiting, caching

If Missing:

Context	Skill/Methodology
Service architecture	faion-software-architect → microservices-architecture
Client requirements	faion-frontend-developer, faion-product-manager

---

api-testing.md

Required Context:

• API contracts defined
• Test data strategy
• CI/CD integration needs
• Contract testing requirements

Decision Tree:

Start
├── Contract testing needed?
│   └── YES → Use Pact or similar
├── Integration tests?
│   └── YES → Test against real/mock server
├── Performance testing?
│   └── YES → Load testing with k6, Artillery
└── Minimum: contract + integration tests

If Missing:

Context	Skill/Methodology
API contracts	api-openapi-spec.md
Testing strategy	faion-testing-developer → integration-testing
CI/CD	faion-cicd-engineer → ci-cd-pipelines

---

api-monitoring.md

Required Context:

• SLOs defined (latency, availability)
• Alerting requirements
• Tracing needs
• Log aggregation setup

Decision Tree:

Start
├── SLOs defined?
│   └── NO → Define first (faion-software-architect)
├── Distributed system?
│   └── YES → Need distributed tracing
├── Need business metrics?
│   └── YES → Custom metrics + dashboards
└── Minimum: latency, errors, throughput (RED)

If Missing:

Context	Skill/Methodology
SLOs	faion-software-architect → quality-attributes
Observability	faion-software-architect → observability-architecture
Alerting	faion-cicd-engineer → monitoring-alerting

---

faion-api-developer v1.1 | 19 methodologies | Context-aware