sop-api-development

What this skill does

# SOP: REST API Development

Complete REST API development using Test-Driven Development and multi-agent coordination.

## Timeline: 2 Weeks

**Phases**:
1. Planning & Design (Days 1-2)
2. Development (Days 3-8)
3. Testing & Documentation (Days 9-11)
4. Deployment (Days 12-14)

---

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

### Day 1: Requirements & Architecture

**Sequential Workflow**:

```javascript
// Step 1: Gather Requirements
await Task("Product Manager", `
Define API requirements:
- List all endpoints needed
- Define data models and relationships
- Specify authentication/authorization
- Define rate limiting and quotas
- Identify third-party integrations

Store requirements: api-dev/rest-api-v2/requirements
`, "planner");

// Step 2: API Design
await Task("System Architect", `
Using requirements: api-dev/rest-api-v2/requirements

Design:
- RESTful API structure (resources, HTTP methods)
- URL patterns and versioning strategy
- Request/response formats (JSON schemas)
- Error handling patterns
- API security architecture

Generate OpenAPI 3.0 specification
Store: api-dev/rest-api-v2/openapi-spec
`, "system-architect");

// Step 3: Database Design
await Task("Database Architect", `
Using API spec: api-dev/rest-api-v2/openapi-spec

Design database:
- Schema design (tables, columns, types)
- Relationships and foreign keys
- Indexes for performance
- Migration strategy
- Backup and recovery plan

Generate SQL schema
Store: api-dev/rest-api-v2/db-schema
`, "code-analyzer");
```

### Day 2: Test Planning

```javascript
// Step 4: Test Strategy
await Task("QA Engineer", `
Using:
- API spec: api-dev/rest-api-v2/openapi-spec
- DB schema: api-dev/rest-api-v2/db-schema

Create test plan:
- Unit test strategy (per endpoint)
- Integration test scenarios
- E2E test workflows
- Performance test targets
- Security test cases

Store test plan: api-dev/rest-api-v2/test-plan
`, "tester");

// Step 5: DevOps Planning
await Task("DevOps Engineer", `
Plan infrastructure:
- Environment setup (dev, staging, prod)
- CI/CD pipeline design
- Monitoring and logging strategy
- Deployment strategy (blue-green)
- Rollback procedures

Store DevOps plan: api-dev/rest-api-v2/devops-plan
`, "cicd-engineer");
```

**Deliverables**:
- API requirements document
- OpenAPI 3.0 specification
- Database schema
- Test plan
- DevOps plan

---

## Phase 2: Development (Days 3-8)

### Day 3-4: Setup & Foundation

**Parallel Workflow**:

```javascript
// Initialize development environment
await mcp__ruv-swarm__swarm_init({
  topology: 'hierarchical',
  maxAgents: 5,
  strategy: 'specialized'
});

// Parallel setup
const [projectSetup, dbSetup, ciSetup] = await Promise.all([
  Task("Backend Developer", `
Project setup:
- Initialize Node.js/Express project
- Configure TypeScript
- Set up ESLint + Prettier
- Configure environment variables
- Install dependencies (express, prisma, jest, etc.)

Store project structure: api-dev/rest-api-v2/project-setup
`, "backend-dev"),

  Task("Database Specialist", `
Database setup:
- Create PostgreSQL database
- Run initial migrations
- Seed test data
- Configure connection pooling
- Set up backup scripts

Store DB credentials (encrypted): api-dev/rest-api-v2/db-config
`, "code-analyzer"),

  Task("DevOps Engineer", `
CI/CD setup:
- Configure GitHub Actions workflow
- Set up Docker containers
- Configure environment secrets
- Set up code quality checks
- Configure automated testing

Store CI config: api-dev/rest-api-v2/ci-config
`, "cicd-engineer")
]);
```

### Day 5-6: Core Development (TDD)

**Sequential per Endpoint** (Example: User Authentication):

```javascript
// For each endpoint, follow TDD cycle:

// 1. Write Tests First
await Task("Test Engineer", `
Write tests for: POST /api/auth/register

Unit tests:
- Valid registration with email/password
- Duplicate email rejection
- Password strength validation
- Email format validation

Integration tests:
- Database record creation
- Email verification trigger
- Response format validation

Store tests: api-dev/rest-api-v2/tests/auth/register.test.ts
`, "tester");

// 2. Implement to Pass Tests
await Task("Backend Developer", `
Implement: POST /api/auth/register

Following tests at: api-dev/rest-api-v2/tests/auth/register.test.ts

Implementation:
- Request validation (email, password)
- Password hashing (bcrypt)
- User creation in database
- Send verification email
- Return JWT token

All tests must pass
Store implementation: api-dev/rest-api-v2/src/auth/register.ts
`, "backend-dev");

// 3. Refactor & Optimize
await Task("Code Reviewer", `
Review implementation: api-dev/rest-api-v2/src/auth/register.ts

Check:
- Code quality and style
- Security best practices
- Performance optimization
- Error handling completeness

Suggest improvements
Store review: api-dev/rest-api-v2/reviews/auth/register-review.md
`, "reviewer");

// Repeat for all endpoints (login, refresh, logout, etc.)
```

### Day 7-8: Advanced Features

**Parallel Development**:

```javascript
const [auth, crud, search, webhook] = await Promise.all([
  Task("Auth Specialist", `
Implement authentication middleware:
- JWT verification
- Token refresh logic
- Role-based access control (RBAC)
- API key authentication

Store: api-dev/rest-api-v2/src/middleware/auth.ts
`, "backend-dev"),

  Task("CRUD Developer", `
Implement CRUD operations for all resources:
- GET /api/resources (list with pagination, filtering, sorting)
- GET /api/resources/:id (single resource)
- POST /api/resources (create)
- PUT /api/resources/:id (update)
- DELETE /api/resources/:id (delete)

Store: api-dev/rest-api-v2/src/resources/
`, "backend-dev"),

  Task("Search Developer", `
Implement search functionality:
- Full-text search across resources
- Advanced filtering (operators: eq, gt, lt, contains)
- Faceted search with aggregations
- Search result ranking

Store: api-dev/rest-api-v2/src/search/
`, "backend-dev"),

  Task("Webhook Developer", `
Implement webhook system:
- Webhook registration endpoints
- Event triggering system
- Retry logic with exponential backoff
- Webhook signature verification

Store: api-dev/rest-api-v2/src/webhooks/
`, "backend-dev")
]);
```

**Deliverables**:
- Working API with all endpoints implemented
- All tests passing (unit + integration)
- Code reviewed and optimized

---

## Phase 3: Testing & Documentation (Days 9-11)

### Day 9: Comprehensive Testing

**Parallel Testing**:

```javascript
const [e2eTests, perfTests, securityTests] = await Promise.all([
  Task("E2E Test Engineer", `
End-to-end testing:
- Complete user workflows (register → login → CRUD → logout)
- Error scenarios (invalid input, unauthorized access)
- Edge cases (rate limiting, concurrent requests)

Run E2E test suite
Store results: api-dev/rest-api-v2/test-results/e2e
`, "tester"),

  Task("Performance Tester", `
Performance testing:
- Load testing (1000 req/sec target)
- Stress testing (find breaking point)
- Endurance testing (24-hour sustained load)
- API response time < 200ms (p95)

Run benchmarks
Store metrics: api-dev/rest-api-v2/test-results/performance
`, "perf-analyzer"),

  Task("Security Tester", `
Security testing:
- OWASP API Security Top 10 checks
- SQL injection testing
- XSS vulnerability testing
- Authentication/authorization bypass attempts
- Rate limiting validation

Run security scan
Store audit: api-dev/rest-api-v2/test-results/security
`, "security-manager")
]);
```

### Day 10-11: Documentation

**Parallel Documentation**:

```javascript
const [apiDocs, devDocs, runbook] = await Promise.all([
  Task("API Documentation Writer", `
Create API documentation:
- OpenAPI/Swagger interactive docs
- Authentication guide
- Endpoint reference (all endpoints)
- Code examples (cURL, JavaScript, Python)
- Rate limiting and quotas
- Error codes and handling

Host Swagger UI
Store: api-dev/rest-api-v2/docs/api-reference
`, "api-docs"),

  Task("Developer Documentation", `
Create developer guide:
- Getting started (setup, authentication)
- Tutorial (common workflows)
-