Agent-Skills.md

Agent Skills: API Developer Skill

API development: REST, GraphQL, OpenAPI, versioning, auth, rate limiting.

UncategorizedID: faionfaion/faion-network/faion-api-developer

Repository

faionfaion/faion-network
faionfaionLicense: NOASSERTION
2

Install this agent skill to your local

pnpm dlx add-skill https://github.com/faionfaion/faion-network/tree/HEAD/skills/faion-api-developer

Skill Files

Browse the full folder contents for faion-api-developer.

Download Skill

Loading file tree…

skills/faion-api-developer/SKILL.md

Skill Metadata

Name
faion-api-developer
Description
"API development: REST, GraphQL, OpenAPI, versioning, auth, rate limiting."

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 | | Real-time | | WebSocket design | WebSocket patterns, real-time APIs | websocket-design.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