docs/development/api-reference.md

API Documentation Reference

This document provides an overview of all available API documentation.

Documentation Types

The project maintains multiple types of API documentation:

1. FastAPI REST Endpoints - HTTP API for client-server communication
2. Frontend JavaScript Modules - Client-side application code
3. Backend Python Modules - Server-side business logic and utilities
4. Auto-generated OpenAPI Client - Type-safe JavaScript client for REST endpoints

1. FastAPI REST API

Live Documentation

When the development server is running, interactive API documentation is available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

These provide:

• Interactive endpoint testing
• Request/response schemas
• Authentication requirements
• Parameter validation rules

OpenAPI Schema

The complete OpenAPI 3.0 schema is available at:

• JSON: http://localhost:8000/openapi.json

This schema is used to auto-generate the frontend API client.

REST Endpoint Categories

Authentication

• /api/v1/auth/login - User login
• /api/v1/auth/logout - User logout
• /api/v1/auth/session - Session validation

Collections

• /api/v1/collections - List, create, update, delete collections
• /api/v1/collections/{id} - Get, update, delete specific collection

Files

• /api/v1/files/list - List accessible files
• /api/v1/files/{doc_id} - Serve file content (PDF/XML)
• /api/v1/files/save - Save TEI XML content
• /api/v1/files/upload - Upload new PDF
• /api/v1/files/copy - Copy files between collections
• /api/v1/files/move - Move files between collections
• /api/v1/files/delete - Soft-delete files

File Locks

• /api/v1/files/locks - Get current locks
• /api/v1/files/check_lock - Check lock status
• /api/v1/files/acquire_lock - Acquire editing lock
• /api/v1/files/release_lock - Release editing lock
• /api/v1/files/heartbeat - Extend lock expiration

Extraction

• /api/v1/extraction/list - List available extractors
• /api/v1/extraction - Extract TEI from PDF

Validation

• /api/v1/validation - Validate TEI XML
• /api/v1/validation/autocomplete-data - Get autocomplete suggestions

Schema

• /api/v1/schema/{type}/{variant} - Get XSD/RelaxNG schemas

Sync

• /api/v1/sync/status - Get WebDAV sync status
• /api/v1/sync - Trigger sync operation
• /api/v1/sync/conflicts - List sync conflicts
• /api/v1/sync/resolve-conflict - Resolve conflict

SSE (Server-Sent Events)

• /api/v1/sse/subscribe - Subscribe to real-time events
• /api/v1/sse/test/echo - Test event broadcast

Users & RBAC

• /api/v1/users - User management
• /api/v1/groups - Group management
• /api/v1/roles - Role management

2. Frontend JavaScript API

Generated HTML Documentation

Frontend module documentation is auto-generated from JSDoc comments using the jsdoc tool with the better-docs theme.

Generate frontend docs:

npm run docs:frontend

View frontend docs:

npm run docs:serve
# Open http://localhost:8080/frontend

Location: docs/api/frontend/ (git-ignored)

Module Categories

Plugin System

• plugin-base.js - Base plugin class with lifecycle hooks
• plugin-manager.js - Plugin registration and lifecycle management
• plugin-context.js - Plugin API context for state/events

State Management

• state-manager.js - Application state with change detection
• application.js - Main application controller

UI System

• ui-system.js - UI element registration and navigation
• panels/*.js - Panel management

RBAC

• rbac/entity-manager.js - Role-based access control entities
• acl-utils.js - Access control utilities

Editors

• xmleditor.js - CodeMirror-based XML editor
• navigatable-xmleditor.js - XML editor with navigation
• pdfviewer.js - PDF.js viewer integration

Utilities

• utils.js - General utilities
• sl-utils.js - Shoelace component helpers
• browser-utils.js - Browser compatibility utilities

API Client

• api-client-v1.js - Auto-generated FastAPI client (DO NOT EDIT)

3. Backend Python API

Generated HTML Documentation

Backend module documentation is auto-generated from Google-style docstrings using pdoc.

Generate backend docs:

npm run docs:backend

View backend docs:

npm run docs:serve
# Open http://localhost:8080/backend

Location: docs/api/backend/ (git-ignored)

Generated JSON Documentation

Machine-readable JSON documentation for AI code assistants.

Generate backend JSON:

npm run docs:backend:json

Location: docs/api/backend-api.json (git-ignored, ~980KB)

Usage: This JSON file contains complete class/function signatures with type annotations and docstrings. Use it to verify API existence and signatures before writing code that calls backend methods.

Module Categories

Core Libraries (fastapi_app/lib/)

• access_control.py - Document permission checking
• auth.py - User authentication
• database.py - SQLite database operations
• file_repository.py - File metadata CRUD
• file_storage.py - Physical file storage
• locking.py - File editing locks
• sessions.py - Session management
• tei_utils.py - TEI XML processing utilities
• user_utils.py - User/group/collection utilities
• xml_utils.py - XML validation and processing
• migrations/ - Database migration infrastructure

Plugin System (fastapi_app/plugins/)

• edit_history/ - Edit history tracking
• iaa_analyzer/ - Inter-annotator agreement analysis
• sample_analyzer/ - Sample data analysis
• annotation_versions_analyzer/ - Version comparison

API Routes (fastapi_app/routers/)

• auth.py - Authentication endpoints
• collections.py - Collection management
• files_*.py - File operations (list, serve, save, upload, locks)
• extraction.py - TEI extraction
• validation.py - XML validation
• sync.py - WebDAV sync
• sse.py - Server-sent events
• users.py, groups.py, roles.py - RBAC management

4. Auto-generated API Client

Generation

The frontend API client is auto-generated from the FastAPI OpenAPI schema:

Regenerate client:

npm run generate-client

Check if outdated:

npm run generate-client:check

Location: app/src/modules/api-client-v1.js (DO NOT EDIT MANUALLY)

Usage

import { ApiClientV1 } from './modules/api-client-v1.js';

const client = new ApiClientV1({ baseUrl: '/api/v1', sessionId });

// Type-safe method calls
const files = await client.files.list({ collection: 'manuscripts' });
const content = await client.files.serve({ doc_id: 'doc-123', type: 'xml' });
await client.files.save({ doc_id: 'doc-123', content: '<TEI>...</TEI>' });

All methods are strongly typed based on the OpenAPI schema.

Documentation Commands

Generate All Documentation

npm run docs:generate

Generates:

• Frontend HTML docs
• Backend HTML docs
• Backend JSON docs

Generate Specific Documentation

npm run docs:frontend        # Frontend HTML only
npm run docs:backend         # Backend HTML only
npm run docs:backend:json    # Backend JSON only

Serve Documentation Locally

npm run docs:serve

Starts HTTP server at http://localhost:8080 serving:

• frontend/ - Frontend module docs
• backend/ - Backend module docs
• backend-api.json - Machine-readable backend API

Clean Generated Documentation

npm run docs:clean

Removes all generated documentation files.

Programmatic API Access

Environment Variables for CLI Scripts

All CLI scripts and external tools that access the HTTP API should support these environment variables (from .env file):

# API credentials
API_USER=admin
API_PASSWORD=admin

# API base URL (default: http://localhost:8000)
API_BASE_URL=http://localhost:8000

Example usage:

# Create .env file with credentials
cat > .env << EOF
API_USER=admin
API_PASSWORD=admin
API_BASE_URL=http://localhost:8000
EOF

# Run CLI script (will read credentials from .env)
node bin/batch-extract.js /path/to/pdfs --collection my_collection --extractor mock-extractor

# Or override via CLI parameters
node bin/batch-extract.js /path/to/pdfs \
  --user admin \
  --password admin \
  --base-url http://localhost:8000 \
  --collection my_collection \
  --extractor mock-extractor

CLI scripts should:

• Accept optional --env <path> parameter (default: ./.env)
• Support --user, --password, --base-url CLI parameters that override env vars
• Use SHA-256 password hashing for authentication (matching frontend)
• Make authenticated requests with X-Session-ID header

Example implementations:

• bin/batch-extract.js - Batch PDF metadata extraction

Best Practices

For Developers

Before adding new code:

1. Check generated documentation to verify APIs don't already exist
2. Use backend JSON (docs/api/backend-api.json) to verify method signatures
3. Consult frontend HTML docs to understand existing patterns
4. Review FastAPI docs at /docs for endpoint requirements

After adding new code:

1. Add comprehensive JSDoc comments (frontend)
2. Add Google-style docstrings (backend)
3. Regenerate documentation: npm run docs:generate
4. Verify documentation renders correctly: npm run docs:serve

When creating new endpoints:

1. Add endpoint to appropriate router in fastapi_app/routers/
2. Regenerate API client: npm run generate-client
3. Check client was updated correctly
4. Update integration tests

For AI Code Assistants

Before suggesting new APIs:

1. Read class definition or module exports
2. Check docs/api/backend-api.json for Python signatures
3. Check frontend HTML docs for JavaScript exports
4. Verify in FastAPI docs at /docs

Never:

• Assume a method exists without verification
• Use generic "object" types when specific types exist in docs
• Skip documentation generation after adding new code

Related Documentation

• Architecture Overview - System design and components
• Database Schema - Database structure and migrations
• Access Control - RBAC and permissions
• Plugin System - Creating plugins
• Testing Guide - API testing patterns
• Contributing - Development workflow