when-building-backend-api-orchestrate-api-development

What this skill does

# API Development Orchestration Workflow

Complete REST API development workflow using Test-Driven Development and multi-agent coordination. Orchestrates 8-12 specialist agents across planning, architecture design, TDD implementation, testing, documentation, and production deployment in a systematic 2-week process.

## Overview

This SOP implements a comprehensive API development workflow emphasizing quality through Test-Driven Development (TDD). The workflow balances speed with thoroughness, using hierarchical coordination for planning phases and parallel execution for development and testing. Each phase produces validated deliverables that subsequent phases consume, ensuring continuity and traceability.

The TDD approach ensures high test coverage (>90%), reduces bugs, and produces well-designed, maintainable code. Parallel execution of specialized reviews accelerates quality validation while maintaining comprehensive coverage of security, performance, and architectural concerns.

## Trigger Conditions

Use this workflow when:
- Building a new REST API or microservice from scratch
- Migrating existing API to modern architecture with comprehensive testing
- Need systematic TDD approach with documented test coverage
- Require production-ready API with security, performance, and scalability validation
- Timeline is 2-4 weeks with clear milestones and deliverables
- Quality gates (testing, security, performance) are non-negotiable
- Need comprehensive API documentation and operational runbooks

## Orchestrated Agents (12 Total)

### Planning & Architecture Agents
- **`product-manager`** - Requirements gathering, endpoint definition, API contracts, success criteria
- **`system-architect`** - API architecture design, RESTful patterns, versioning, error handling strategy
- **`database-architect`** - Schema design, query optimization, indexing, migration planning
- **`qa-engineer`** - Test planning, TDD strategy, coverage targets, performance benchmarks

### Development Agents (TDD Cycle)
- **`tester`** - Write tests first (red phase), integration tests, E2E scenarios
- **`backend-developer`** - Implement to pass tests (green phase), refactor for quality
- **`code-reviewer`** - Code quality review, refactoring suggestions, best practices validation

### Quality & Validation Agents
- **`security-specialist`** - Security architecture, OWASP validation, penetration testing
- **`performance-analyst`** - Load testing, stress testing, bottleneck identification, optimization
- **`api-documentation-specialist`** - OpenAPI specs, developer guides, code examples

### Deployment & Operations Agents
- **`devops-engineer`** - CI/CD pipeline, Docker/K8s deployment, infrastructure as code
- **`production-validator`** - Pre-production validation, go/no-go decision, smoke testing
- **`performance-monitor`** - Production monitoring, logging, alerting, SLO tracking

## Workflow Phases

### Phase 1: Planning & Design (Days 1-2, Sequential)

**Duration**: 2 days
**Execution Mode**: Sequential analysis and design
**Agents**: `product-manager`, `system-architect`, `database-architect`, `qa-engineer`

**Process**:

1. **Gather API Requirements** (Day 1 Morning)
   ```bash
   npx claude-flow hooks pre-task --description "API Development: ${API_NAME}"
   npx claude-flow swarm init --topology hierarchical --max-agents 12 --strategy specialized
   npx claude-flow agent spawn --type planner
   ```

   **Product Manager** defines:
   - Complete endpoint list with HTTP methods (GET, POST, PUT, DELETE, PATCH)
   - Data models and relationships (entities, attributes, cardinality)
   - Authentication and authorization requirements (OAuth, JWT, RBAC)
   - Rate limiting and quota specifications
   - Third-party integrations and external dependencies
   - API versioning strategy (URL path, header, content negotiation)
   - Success metrics and SLAs (response time, uptime, throughput)

   **Memory Storage**:
   ```bash
   npx claude-flow memory store --key "api-development/${API_ID}/phase-1/product-manager/requirements" \
     --value "${REQUIREMENTS_JSON}"
   ```

2. **Design API Architecture** (Day 1 Afternoon)
   ```bash
   npx claude-flow memory retrieve --key "api-development/${API_ID}/phase-1/product-manager/requirements"
   npx claude-flow agent spawn --type system-architect
   ```

   **System Architect** designs:
   - RESTful API structure following Richardson Maturity Model
   - URL patterns and resource naming conventions
   - Request/response formats with JSON schemas
   - Error handling patterns (error codes, messages, stack traces)
   - Pagination, filtering, sorting, and search strategies
   - Caching strategy (ETags, cache-control headers)
   - API security architecture (authentication flow, token management)
   - Versioning and backward compatibility approach

   Generate OpenAPI 3.0 specification:
   ```bash
   npx claude-flow memory store --key "api-development/${API_ID}/phase-1/system-architect/openapi-spec" \
     --value "${OPENAPI_YAML}"
   ```

3. **Design Database Schema** (Day 2 Morning)
   ```bash
   npx claude-flow memory retrieve --key "api-development/${API_ID}/phase-1/system-architect/openapi-spec"
   npx claude-flow agent spawn --type code-analyzer
   ```

   **Database Architect** creates:
   - Normalized schema design (3NF) with entity-relationship diagram
   - Table definitions (columns, data types, constraints, defaults)
   - Relationships and foreign key constraints
   - Indexes for query performance (primary, secondary, composite)
   - Migration scripts (up and down migrations)
   - Backup and recovery strategy
   - Scaling strategy (sharding, replication, read replicas)

   Generate SQL schema and migrations:
   ```bash
   npx claude-flow memory store --key "api-development/${API_ID}/phase-1/database-architect/schema" \
     --value "${SCHEMA_SQL}"
   npx claude-flow memory store --key "api-development/${API_ID}/phase-1/database-architect/migrations"
   ```

4. **Create Test Strategy** (Day 2 Afternoon)
   ```bash
   npx claude-flow memory retrieve --pattern "api-development/${API_ID}/phase-1/*"
   npx claude-flow agent spawn --type tester
   ```

   **QA Engineer** plans:
   - Unit test strategy (per endpoint, per function)
   - Integration test scenarios (database, external APIs)
   - End-to-end test workflows (complete user journeys)
   - Performance test targets (load, stress, endurance)
   - Security test cases (OWASP API Security Top 10)
   - Test data management (fixtures, factories, mocks)
   - Coverage targets (>90% for new code)
   - CI/CD test automation strategy

   **Memory Storage**:
   ```bash
   npx claude-flow memory store --key "api-development/${API_ID}/phase-1/qa-engineer/test-plan"
   npx claude-flow hooks post-task --task-id "phase-1-planning"
   ```

**Outputs**:
- API requirements document with complete endpoint specifications
- OpenAPI 3.0 specification (machine-readable contract)
- Database schema with ER diagram and migrations
- Comprehensive test plan with coverage targets
- DevOps plan with infrastructure requirements

**Success Criteria**:
- [ ] All API endpoints documented in OpenAPI spec
- [ ] Database schema normalized and indexed for performance
- [ ] Test strategy covers all quality dimensions
- [ ] Architecture approved by technical stakeholders
- [ ] Phase 1 deliverables stored in memory

---

### Phase 2: Foundation Setup (Days 3-4, Parallel)

**Duration**: 2 days
**Execution Mode**: Parallel infrastructure setup
**Agents**: `backend-developer`, `database-architect`, `devops-engineer`

**Process**:

1. **Initialize Development Environment**
   ```bash
   npx claude-flow swarm init --topology mesh --max-agents 3 --strategy adaptive
   npx claude-flow task orchestrate --strategy parallel
   ```

2. **Parallel Setup Execution**

   Spawn all setup agents concurrently:
   ```bash
   # Backend project setup
   npx claude-flow agent spawn --type backend-dev --capabilities "nodejs,typescript,express"

   # Database setup