Faion API Developer

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:

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

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

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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