when-building-backend-api-orchestrate-api-development
Use when building a production-ready REST API from requirements through deployment. Orchestrates 8-12 specialist agents across 5 phases using Test-Driven Development methodology. Covers planning, architecture, TDD implementation, comprehensive testing, documentation, and blue-green deployment over a 2-week timeline with emphasis on quality and reliability.
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-21
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: when-building-backend-api-orchestrate-api-development
type: sop-workflow
description: |
Use when building a production-ready REST API from requirements through deployment.
Orchestrates 8-12 specialist agents across 5 phases using Test-Driven Development methodology.
Covers planning, architecture, TDD implementation, comprehensive testing, documentation, and
blue-green deployment over a 2-week timeline with emphasis on quality and reliability.
agents:
- product-manager
- system-architect
- database-architect
- qa-engineer
- backend-developer
- security-specialist
- performance-analyst
- api-documentation-specialist
- devops-engineer
- production-validator
- performance-monitor
- code-reviewer
phases: 5
memory_pattern: "api-development/{api-id}/phase-{N}/{agent}/{deliverable}"
---
# 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
npx claude-flow agent spawn --type code-analyzer --capabilities "postgresql,prisma,migrations"
# CI/CD setup
npx claude-flow agent spawn --type cicd-engineer --capabilities "github-actions,docker,testing"
```
**Backend Developer** initializes:
- Node.js/Express (or FastAPI/Flask/Spring Boot) project
- TypeScript configuration (strict mode, path aliases)
- ESLint + Prettier (code quality and formatting)
- Environment variable management (dotenv, validation)
- Dependency installation (express, prisma, jest, supertest, etc.)
- Project structure (controllers, services, models, middleware)
- Logging framework (Winston, Pino) with structured logging
- Error handling middleware (global error handler)
**Memory Pattern**: `api-development/${API_ID}/phase-2/backend-developer/project-setup`
**Database Architect** sets up:
- PostgreSQL database (or MySQL/MongoDB)
- Connection pooling configuration (pg-pool, connection limits)
- Initial migration execution (create tables, indexes)
- Seed data for development and testing
- Database backup scripts (pg_dump automation)
- Performance monitoring queries (slow query log)
**Memory Pattern**: `api-development/${API_ID}/phase-2/database-architect/db-config`
**DevOps Engineer** configures:
- GitHub Actions workflow (or GitLab CI/Jenkins)
- Docker containers (multi-stage builds for optimization)
- Docker Compose for local development
- Environment secrets management (GitHub Secrets, Vault)
- Automated testing pipeline (run tests on PR)
- Code quality checks (linting, type checking)
- Build artifact generation and storage
**Memory Pattern**: `api-development/${API_ID}/phase-2/devops-engineer/ci-config`
**Coordination Script**:
```bash
npx claude-flow hooks post-edit --file "package.json" \
--memory-key "api-development/${API_ID}/phase-2/setup-complete"
npx claude-flow hooks notify --message "Development environment ready"
```
**Outputs**:
- Initialized project with all dependencies
- Database with schema and seed data
- CI/CD pipeline operational
- Development environment fully functional
**Success Criteria**:
- [ ] Project builds without errors
- [ ] Database connections established and tested
- [ ] CI/CD pipeline runs successfully
- [ ] Local development environment documented
---
### Phase 3: TDD Implementation (Days 5-10, Red-Green-Refactor Cycle)
**Duration**: 6 days
**Execution Mode**: Iterative TDD cycles per endpoint
**Agents**: `tester`, `backend-developer`, `code-reviewer`
**Process**:
This phase follows strict Test-Driven Development:
1. **RED**: Write failing tests (tester agent)
2. **GREEN**: Implement code to pass tests (backend-developer agent)
3. **REFACTOR**: Improve code quality (code-reviewer agent)
**TDD Cycle Example** (POST /api/auth/register endpoint):
1. **RED Phase: Write Failing Tests** (30-60 min per endpoint)
```bash
npx claude-flow agent spawn --type tester
```
**Tester Agent** writes:
```javascript
// Unit tests
describe('POST /api/auth/register', () => {
test('should register user with valid email and password', async () => {
const response = await request(app)
.post('/api/auth/register')
.send({ email: 'user@example.com', password: 'SecurePass123!' });
expect(response.status).toBe(201);
expect(response.body).toHaveProperty('token');
expect(response.body.user.email).toBe('user@example.com');
});
test('should reject duplicate email registration', async () => {
// Create user first
await createUser({ email: 'existing@example.com' });
const response = await request(app)
.post('/api/auth/register')
.send({ email: 'existing@example.com', password: 'Pass123!' });
expect(response.status).toBe(409);
expect(response.body.error).toContain('Email already exists');
});
test('should validate password strength', async () => {
const response = await request(app)
.post('/api/auth/register')
.send({ email: 'user@example.com', password: 'weak' });
expect(response.status).toBe(400);
expect(response.body.error).toContain('Password must be at least 8 characters');
});
test('should validate email format', async () => {
const response = await request(app)
.post('/api/auth/register')
.send({ email: 'invalid-email', password: 'SecurePass123!' });
expect(response.status).toBe(400);
expect(response.body.error).toContain('Invalid email format');
});
});
// Integration tests
describe('User Registration Integration', () => {
test('should create user in database', async () => {
const response = await request(app)
.post('/api/auth/register')
.send({ email: 'dbtest@example.com', password: 'Pass123!' });
const userInDb = await db.user.findUnique({ where: { email: 'dbtest@example.com' } });
expect(userInDb).toBeDefined();
expect(userInDb.passwordHash).not.toBe('Pass123!'); // Password should be hashed
});
});
```
**Memory Storage**:
```bash
npx claude-flow memory store --key "api-development/${API_ID}/phase-3/tester/auth/register-tests" \
--value "${TEST_FILE_CONTENT}"
```
2. **GREEN Phase: Implement to Pass Tests** (1-2 hours per endpoint)
```bash
npx claude-flow memory retrieve --key "api-development/${API_ID}/phase-3/tester/auth/register-tests"
npx claude-flow agent spawn --type backend-dev
```
**Backend Developer** implements:
```javascript
// POST /api/auth/register implementation
router.post('/register', async (req, res, next) => {
try {
// Validate input
const { email, password } = req.body;
if (!isValidEmail(email)) {
return res.status(400).json({ error: 'Invalid email format' });
}
if (password.length < 8) {
return res.status(400).json({ error: 'Password must be at least 8 characters' });
}
// Check for duplicate email
const existingUser = await db.user.findUnique({ where: { email } });
if (existingUser) {
return res.status(409).json({ error: 'Email already exists' });
}
// Hash password
const passwordHash = await bcrypt.hash(password, 10);
// Create user
const user = await db.user.create({
data: { email, passwordHash }
});
// Generate JWT token
const token = jwt.sign({ userId: user.id }, process.env.JWT_SECRET, { expiresIn: '7d' });
res.status(201).json({
token,
user: { id: user.id, email: user.email }
});
} catch (error) {
next(error);
}
});
```
Run tests and verify all pass:
```bash
npm test -- auth/register.test.js
# All tests should pass (GREEN)
```
**Memory Storage**:
```bash
npx claude-flow memory store --key "api-development/${API_ID}/phase-3/backend-developer/auth/register-impl"
```
3. **REFACTOR Phase: Improve Code Quality** (30 min per endpoint)
```bash
npx claude-flow memory retrieve --pattern "api-development/${API_ID}/phase-3/*/auth/register-*"
npx claude-flow agent spawn --type reviewer
```
**Code Reviewer** evaluates:
- Code readability and clarity
- Duplication (extract validation to middleware)
- Security best practices (password hashing, JWT signing)
- Error handling completeness
- Performance optimizations
Suggests refactoring:
```javascript
// Extracted validation middleware
const validateRegistration = (req, res, next) => {
const { email, password } = req.body;
if (!isValidEmail(email)) {
return res.status(400).json({ error: 'Invalid email format' });
}
if (password.length < 8) {
return res.status(400).json({ error: 'Password must be at least 8 characters' });
}
next();
};
// Cleaner route handler
router.post('/register', validateRegistration, async (req, res, next) => {
try {
const user = await authService.registerUser(req.body);
const token = authService.generateToken(user.id);
res.status(201).json({ token, user });
} catch (error) {
if (error.code === 'DUPLICATE_EMAIL') {
return res.status(409).json({ error: 'Email already exists' });
}
next(error);
}
});
```
**Memory Storage**:
```bash
npx claude-flow memory store --key "api-development/${API_ID}/phase-3/code-reviewer/auth/register-review"
npx claude-flow hooks post-edit --file "src/routes/auth.ts"
```
4. **Repeat TDD Cycle for All Endpoints** (Days 5-10)
Apply RED-GREEN-REFACTOR to all endpoints:
- Authentication (register, login, logout, refresh, reset-password)
- CRUD operations (create, read, update, delete for all resources)
- Search and filtering
- Pagination and sorting
- File uploads (if applicable)
- Webhooks (if applicable)
**Progress Tracking**:
```bash
npx claude-flow memory store --key "api-development/${API_ID}/phase-3/progress" \
--value '{"completed_endpoints": 12, "total_endpoints": 20, "coverage": 93.5}'
```
**Outputs**:
- All API endpoints implemented
- Comprehensive test suite with >90% coverage
- Refactored, clean, maintainable code
- All tests passing (green)
**Success Criteria**:
- [ ] All endpoints functional and tested
- [ ] Test coverage exceeds 90%
- [ ] No code quality violations (ESLint passing)
- [ ] Code review approved for all endpoints
- [ ] TDD cycle completed for entire API surface
---
### Phase 4: Testing & Documentation (Days 11-12, Parallel)
**Duration**: 2 days
**Execution Mode**: Parallel validation across multiple dimensions
**Agents**: `qa-engineer`, `security-specialist`, `performance-analyst`, `api-documentation-specialist`
**Process**:
1. **Initialize Testing Swarm**
```bash
npx claude-flow swarm init --topology star --max-agents 4 --strategy specialized
npx claude-flow task orchestrate --strategy parallel --priority high
```
2. **Parallel Testing Execution**
Spawn all testing agents concurrently:
```bash
# E2E testing
npx claude-flow agent spawn --type tester --focus "end-to-end"
# Performance testing
npx claude-flow agent spawn --type perf-analyzer --focus "load-stress-endurance"
# Security testing
npx claude-flow agent spawn --type security-manager --focus "owasp-penetration"
# Documentation
npx claude-flow agent spawn --type api-docs --focus "openapi-developer-guide"
```
**QA Engineer** conducts:
- **End-to-End Testing**: Complete user workflows (register → login → CRUD → logout)
- **Error Scenario Testing**: Invalid inputs, unauthorized access, rate limiting
- **Edge Case Testing**: Boundary conditions, null values, concurrent requests
- **Smoke Testing**: Basic functionality across all endpoints
**Memory Pattern**: `api-development/${API_ID}/phase-4/qa-engineer/e2e-results`
**Performance Analyst** tests:
- **Load Testing**: 1000 req/sec sustained for 10 minut