Api Contracts Backend

For integrators. The backend (BFF) HTTP API contracts — request/response shapes for auth, chat, files, analytics, and admin endpoints.

Component: components/gov-chat-backend/ (Node.js/Express) Base URL: https://<domain>/api (via Kong Gateway) Documentation: Swagger/OpenAPI available at /api-docs

Authentication

All endpoints (except where noted) require Keycloak JWT authentication via Authorization: Bearer <token> header.

Auth middleware: keycloakAuthMiddleware.authenticate (Keycloak OIDC) Admin endpoints: Additional keycloakAuthMiddleware.requireAdmin middleware

Route Domains

1. Authentication Routes (/api/auth)

Route File: routes/auth-routes.js Auth Required: None (login/logout endpoints) Base Paths: /api/auth

2. User Profile Routes (/api/me)

Route File: routes/user-routes.js Auth Required: Yes (all endpoints) Base Paths: /api/me

3. Query Routes (/api/queries, /api/query)

Route File: routes/query-routes.js Auth Required: Yes (all endpoints) Base Paths: /api/queries, /api/query Special: SSE support on /stream endpoint

SSE Event Types (/stream endpoint):

• chunk - LLM response content
• metadata - Query metadata (queryId, responseTime, etc.)
• translation - Translated content (if enabled)
• error - Error message with code
• done - Stream completion

4. Chat History Routes (/api/chat, /api/chat-history)

Route File: routes/chat-history-routes.js Auth Required: Yes (all endpoints) Base Paths: /api/chat, /api/chat-history

5. Analytics Routes (/api/analytics)

Route File: routes/analytics-routes.js Auth Required: Yes (all endpoints) Base Paths: /api/analytics

6. Admin Routes (/api/admin)

Route File: routes/admin-routes.js Auth Required: Yes + Admin Role (all endpoints) Base Paths: /api/admin Middleware: keycloakAuthMiddleware.authenticate + keycloakAuthMiddleware.requireAdmin

7. Service Category Routes (/api/service-categories)

Route File: routes/service-category-routes.js Auth Required: Yes (all endpoints) Base Paths: /api/service-categories

8. Service Routes (/api/services)

Route File: routes/service-routes.js Auth Required: Yes (all endpoints) Base Paths: /api/services

9. Translation Routes (/api/translate)

Route File: routes/translation-routes.js Auth Required: Yes (all endpoints) Base Paths: /api/translate

10. Weather Routes (/api/weather)

Route File: routes/weather-routes.js Auth Required: Yes (all endpoints) Base Paths: /api/weather

11. Logger Routes (/api/logger)

Route File: routes/logger-routes.js Auth Required: Yes + Admin Role (all endpoints) Base Paths: /api/logger Middleware: keycloakAuthMiddleware.authenticate + keycloakAuthMiddleware.requireAdmin

12. Database Operations Routes (/api/database)

Route File: routes/database-operations-routes.js Auth Required: Yes (all endpoints, admin-level operations) Base Paths: /api/database

Document Repository API

Component: components/document-repository/ (Node.js/Express) Base URL: https://<domain>/api (via Kong Gateway)

File Routes (/api/files)

Route File: src/routes/fileRoutes.js Auth Required: Mixed (Admin role for write operations) Base Paths: /api/files

Auth Middleware: authorizeRole(['Admin']) for write operations

Label Routes (/api/labels)

Route File: src/routes/labelRoutes.js Auth Required: Admin Role (all endpoints) Base Paths: /api/labels

Auth Middleware: authorizeRole(['Admin']) for all endpoints

Middleware Reference

Authentication Middleware

Keycloak OIDC Authentication (keycloakAuthMiddleware.authenticate)

• Validates JWT tokens from Keycloak
• Extracts user info from token
• Applied at router level or per-route

Admin Role Check (keycloakAuthMiddleware.requireAdmin)

• Requires realm_access.roles contains admin
• Applied after authenticate middleware

Document Repository Auth

Role Authorization (authorizeRole(['Admin', 'dataprep-service']))

• Checks Keycloak roles
• Supports multiple roles (OR logic)
• Some endpoints allow dataprep-service for internal calls

SSE Streaming Protocol

Endpoint: POST /api/queries/stream

Request Headers

Content-Type: application/json
Authorization: Bearer <token>

Response Headers

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive

Event Format

data: {"type": "chunk", "content": "response text"}

data: {"type": "metadata", "queryId": "123", "responseTime": 1234}

data: {"type": "translation", "content": "translated text"}

data: {"type": "error", "message": "error message", "code": "ERROR_CODE"}

data: {"type": "done", "queryId": "123"}

: keepalive

Environment Control

• Enabled by default — any value other than the literal string false enables it
• Disable explicitly: OPEA_STREAMING=false (returns 501 error)

Error Response Format

All endpoints return JSON errors:

{
  "error": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": {}
}

Common Error Codes

• UNAUTHORIZED - Missing or invalid token
• FORBIDDEN - Insufficient permissions
• NOT_FOUND - Resource not found
• VALIDATION_ERROR - Request validation failed
• STREAMING_DISABLED - SSE streaming disabled (for /stream endpoint)
• CHATQNA_STREAM_ERROR - Upstream OPEA service error
• TRANSLATION_FAILED - Translation service error

Rate Limiting

Applied via Kong Gateway (configured in api-gateway-solution/):

• Default: 100 requests per minute per IP
• Authenticated users: Higher limits based on role
• Admin users: No rate limiting

OpenAPI/Swagger Documentation

Interactive API documentation available at:

• Development: http://localhost:3000/api-docs
• Production: https://<domain>/api-docs

Note: Swagger definitions are inline in route files using JSDoc comments (@swagger, @summary, etc.)

CORS Configuration

Configured in Kong Gateway (api-gateway-solution/):

• Allowed origins: CORS_ALLOWED_ORIGINS env var
• Allowed methods: GET, POST, PUT, PATCH, DELETE, OPTIONS
• Allowed headers: Authorization, Content-Type, X-Requested-With

Version History

• v1.0 - Initial API design (2025)
• v1.1 - Added folder management (2025)
• v1.2 - Added SSE streaming (2025)
• v1.3 - Added label routes (2025)
• v1.4 - Refactored /api/me to singleton pattern (2025)

Related Documentation

• Architecture Overview

• Project overview and conventions