REST API

[rasmi]

REST API for Programmatic Experiment Management

This PR introduces a simple REST API for Deliberate Lab, enabling programmatic access to experiment management functionality from external applications and scripts.

Summary

Adds a complete REST API (/api/v1) for creating, reading, updating, deleting, and exporting experiments. This allows researchers to automate experiment creation, integrate with external tools, and programmatically manage their research workflows using any HTTP client.

Key Features

API Endpoints

• POST /v1/experiments - Create experiments with stage configurations
• GET /v1/experiments - List all accessible experiments
• GET /v1/experiments/:id - Get specific experiment details
• PUT /v1/experiments/:id - Update experiment metadata and stages
• DELETE /v1/experiments/:id - Delete experiments with all associated data
• GET /v1/experiments/:id/export - Export complete experiment data (participants, responses, chat logs, etc.)
• GET /v1/health - API health check (no authentication required)

Authentication & Security

• API Key Authentication: Bearer token authentication with secure key generation
• Permission System: Granular READ/WRITE permissions per API key
• Key Management UI: Web interface in Settings page for creating, viewing, and revoking keys
• Rate Limiting: 100 requests per 15-minute window per API key
• Access Control: Respects experiment ownership and permissions

API Key Management

The Settings page now includes an API Keys section where users can:

• Create new API keys with descriptive names
• View all their API keys with creation dates and last used timestamps
• Copy keys immediately (keys are only shown once during creation)
• Revoke keys they no longer need
• See which permissions each key has (READ, WRITE)

Integration Testing

Comprehensive integration test suite (experiments.api.integration.test.ts) that validates:

• API-created experiments are structurally equivalent to template-created experiments
• Full authentication flow with real API keys
• Actual HTTP requests using supertest
• Tests against multiple production templates (FlipCard, Group Chat, Policy)

Implementation Details

Backend Architecture (functions/src/dl_api/)

Express-based REST API (api.endpoints.ts):

• Express.js application with middleware chain (rate limiting → browser blocking → authentication)
• Proper HTTP status codes and error handling
• JSON request/response bodies
• Deployed as Firebase Cloud Function with 60s timeout, 100 max instances

Experiment Operations (experiments.api.ts):

• Reuses existing Firestore utilities and experiment creation logic
• Transaction-based operations for consistency

API Key Management (api_key.utils.ts):

• Key format: dlb_live_<random_string> for easy identification
• Secure key generation using crypto.randomBytes
• Last used timestamp tracking
• Validation and permission checking utilities

Shared Utilities (api.utils.ts):

• Bearer token extraction and validation
• Permission checking middleware
• IP address normalization for rate limiting
• Request/response validation helpers

Documentation

OpenAPI Specification (docs/api/openapi.yaml):

• Detailed schema definitions for requests and responses
• Authentication instructions with step-by-step key creation guide
• Rate limiting and error response documentation
• Example request/response bodies
• Added to docs site navigation at /developers/api.html