# rest-api

> Ruflo V2 REST API layer with JWT/API-key auth, multi-database service, Claude client, and swarm coordination endpoints

- Skill: `jrennie99-glitch/rest-api` (Agent Skill)
- Install (CLI): `npx skillmds add jrennie99-glitch/rest-api`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jrennie99-glitch/rest-api/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: jrennie99-glitch (https://skillmd.com/u/jrennie99-glitch)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/jrennie99-glitch/rest-api

---


# REST API — Ruflo V2 Swarm Coordination API

Comprehensive REST API layer for the Ruflo swarm coordination system, providing authentication, database access, Claude AI client integration, and full swarm lifecycle management via Express.js endpoints.

## Purpose

Serves as the primary HTTP interface for managing swarms, agents, tasks, and metrics. Combines four core services: AuthService (JWT + API key auth), DatabaseService (multi-engine persistence), ClaudeAPIClient (AI model integration), and SwarmApi (coordination endpoints).

## Source Location

`/tmp/ruflo/v2/src/api/`

## Core Services

### AuthService (`auth-service.ts`)

Handles authentication and role-based access control.

**User Roles:**
- `admin` -- Full system access (all 14 permissions)
- `operator` -- Manage swarms and agents (12 permissions)
- `developer` -- Create and monitor tasks (7 permissions)
- `viewer` -- Read-only access (5 permissions)
- `service` -- Service-to-service authentication (api.access only)

**Permissions System:**
- `swarm.create`, `swarm.read`, `swarm.update`, `swarm.delete`, `swarm.scale`
- `agent.spawn`, `agent.read`, `agent.terminate`
- `task.create`, `task.read`, `task.cancel`
- `metrics.read`, `system.admin`, `api.access`

**Authentication Methods:**
- JWT tokens with configurable expiry (default: 24h)
- API keys with HMAC-SHA256 hashing and constant-time comparison
- Session management with client info tracking (user agent, IP, device)
- Rate limiting: max 5 failed attempts, 15-minute lockout

**Commands:**
```
POST /auth/login          -- Authenticate with email + password
POST /auth/api-key        -- Authenticate with API key
POST /auth/verify         -- Verify JWT token
POST /auth/users          -- Create new user (admin only)
POST /auth/api-keys       -- Generate API key for user
DELETE /auth/api-keys/:id -- Revoke API key
DELETE /auth/sessions/:id -- Invalidate session
```

### DatabaseService (`database-service.ts`)

Multi-engine database abstraction supporting SQLite, MySQL, and PostgreSQL.

**Record Types:**
- `SwarmRecord` -- Swarm instances with topology, strategy, and status
- `AgentRecord` -- Agent lifecycle with capabilities and metadata
- `TaskRecord` -- Task orchestration with priority and strategy
- `MetricRecord` -- Time-series metrics for monitoring
- `EventRecord` -- Audit trail with severity levels

**Configuration:**
```typescript
{
  type: 'sqlite' | 'mysql' | 'postgresql',
  database: string,
  host?: string,
  port?: number,
  poolSize?: number,
  timeout?: number,
  retryAttempts?: number
}
```

### ClaudeAPIClient (`claude-client.ts`)

Direct integration with the Claude API featuring circuit breaker pattern, health checks, and streaming support.

**Supported Models:**
- claude-3-opus-20240229
- claude-3-sonnet-20240229
- claude-3-haiku-20240307
- claude-2.1, claude-2.0, claude-instant-1.2

**Features:**
- Streaming via SSE (Server-Sent Events)
- Circuit breaker with configurable threshold and reset timeout
- Retry with exponential backoff and jitter
- Structured error hierarchy: ClaudeRateLimitError, ClaudeTimeoutError, ClaudeNetworkError, ClaudeAuthenticationError, ClaudeValidationError

### SwarmApi (`swarm-api.ts`)

Express router providing RESTful endpoints for swarm coordination.

**Endpoints:**
```
POST   /swarms                -- Create swarm (topology: hierarchical|mesh|ring|star)
GET    /swarms                -- List all swarms
GET    /swarms/:id            -- Get swarm details
DELETE /swarms/:id            -- Destroy swarm
POST   /swarms/:id/agents     -- Spawn agent in swarm
GET    /swarms/:id/agents     -- List agents
POST   /swarms/:id/tasks      -- Orchestrate task
GET    /swarms/:id/tasks      -- List tasks
GET    /swarms/:id/metrics    -- Get swarm metrics
```

**Configuration:**
```typescript
{
  rateLimit: { windowMs: number, maxRequests: number },
  authentication: { enabled: boolean, apiKeys?: string[], jwtSecret?: string },
  cors: { origins: string[], methods: string[] },
  swagger: { enabled: boolean, title: string, version: string }
}
```

## Error Handling

All endpoints return structured JSON errors:
```json
{
  "error": "Human-readable message",
  "code": "VALIDATION_ERROR | SWARM_ERROR | AUTH_ERROR",
  "details": {}
}
```

HTTP status mapping: 400 (ValidationError), 401 (AuthenticationError), 409 (SwarmError), 500 (internal).

## Implementation Details

- Express.js middleware chain: logging, body validation, auth, route handler, error handler
- Request logging captures method, path, IP, and User-Agent
- All API keys stored as HMAC-SHA256 hashes, never plaintext
- Session cleanup runs periodically to remove expired entries
- Database supports automatic migration on initialization