API Integration

Client Architecture

fetchWithAuth() — Base Client

// apps/portal/src/lib/fetchWithAuth.ts
export async function fetchWithAuth(url: string, options?: FetchWithAuthOptions): Promise<Response>

• Injects Authorization: Bearer {token} from Keycloak
• Sets Content-Type: application/json and Accept: application/json
• Supports skipAuth and skipContentType options

parseApiResponse<T>() — Response Parser

// apps/portal/src/lib/apiResponse.ts
export async function parseApiResponse<T>(response: Response, options?: ParseOptions): Promise<T>

Pipeline: Error check → JSON parse → Unwrap StandardApiResponse → snake_case to camelCase

• Throws ApiError on non-OK responses
• 422 → isValidationError: true with fieldErrors[]
• 204 → returns {}
• Unwraps { status: "success", data: T } wrappers

Service Singleton Pattern

All services use singleton pattern:

class PipelineService {
  private static instance: PipelineService;
  static getInstance(): PipelineService {
    if (!PipelineService.instance) PipelineService.instance = new PipelineService();
    return PipelineService.instance;
  }
}

---

Backend Services

Service	Port	Env Variable	Base Path
API Gateway	8080	VITE_API_BASE_URL	/api
Pipeline	50002	VITE_PIPELINE_API_URL	/api/v1/pipelines
Operator	50001	VITE_OPERATOR_API_URL	/api/v1/operator-templates
Schema Registry	50031	VITE_SCHEMA_REGISTRY_API_URL	/api/v1/schema-registry
Synthetic Data	50032	VITE_SYNTHETIC_DATA_API_URL	/api/v1/generators
Kafka	50034	VITE_KAFKA_API_URL	/api/v1/kafka
Cache	50035	VITE_CACHE_API_URL	/api/v1/keys
Observability	50010	VITE_OBSERVABILITY_API_URL	/api/v1/dashboard

---

All API Endpoints

Pipeline API :50002

Method	Endpoint	Purpose
GET	/api/v1/pipelines	List pipelines (paginated)
GET	/api/v1/pipelines/{id}	Get pipeline details
POST	/api/v1/pipelines	Create pipeline
PUT	/api/v1/pipelines/{id}	Update pipeline
DELETE	/api/v1/pipelines/{id}	Delete pipeline
POST	/api/v1/pipelines/{id}/compile	Compile pipeline
POST	/api/v1/pipelines/{id}/deploy	Deploy pipeline
GET	/api/v1/pipelines/{id}/status	Get deployment status
POST	/api/v1/pipelines/{id}/pause	Pause running pipeline
POST	/api/v1/pipelines/{id}/resume	Resume pipeline
POST	/api/v1/pipelines/{id}/cancel	Cancel pipeline
POST	/api/v1/pipelines/{id}/restore	Restore from savepoint
POST	/api/v1/pipelines/{id}/purge	Purge pipeline state
GET	/api/v1/pipelines/{id}/executions	List executions
GET	/api/v1/pipelines/{id}/savepoints	List savepoints
POST	/api/v1/pipelines/{id}/savepoints/trigger	Trigger savepoint
DELETE	/api/v1/pipelines/{id}/savepoints?path=...	Delete savepoint
GET	/api/v1/pipelines/{id}/checkpoints	List checkpoints
GET	/api/v1/pipelines/{id}/kafka/offsets	Get Kafka offsets

Operator API :50001

Method	Endpoint	Purpose
GET	/api/v1/operator-templates	List all operator templates
GET	/api/v1/operator-templates/{id}	Get template details
GET	/api/v1/operators/{id}/defaults	Get default config
POST	/api/v1/operators/{id}/validate	Validate config
GET	/api/v1/operators/{id}/schema/inputs/{name}	Get input schema

Expression Library API :50001

Method	Endpoint	Purpose
GET	/api/v1/expression-library/templates	List expression templates
POST	/api/v1/expression-library/evaluate	Evaluate expression

Schema Registry API :50031

Method	Endpoint	Purpose
GET	/api/v1/schema-registry/schemas	List schemas (filterable)
GET	/api/v1/schema-registry/schemas/{id}	Get schema details
POST	/api/v1/schema-registry/schemas	Create schema
PUT	/api/v1/schema-registry/schemas/{id}	Update schema
DELETE	/api/v1/schema-registry/schemas/{id}	Delete schema
GET	/api/v1/schema-registry/schemas/{id}/versions	List versions
POST	/api/v1/schema-registry/schemas/{id}/versions	Create version
PUT	.../versions/{vId}/fields/{name}/pii	Mark field as PII

Synthetic Data API :50032

Method	Endpoint	Purpose
GET	/api/v1/generators	List generators (paginated)
GET	/api/v1/generators/{id}	Get generator details
POST	/api/v1/generators	Create generator
PUT	/api/v1/generators/{id}	Update generator
DELETE	/api/v1/generators/{id}	Delete generator
GET	/api/v1/generators/{id}/metrics	Get metrics
POST	/api/v1/generators/{id}/start	Start generation
POST	/api/v1/generators/{id}/pause	Pause generation
POST	/api/v1/generators/{id}/stop	Stop generation
POST	/api/v1/generators/{id}/validate-schema	Validate schema
GET	/api/v1/pools	List data pools
GET	/api/v1/universes	List universes
POST	/api/v1/universes	Create universe

Kafka API :50034

Method	Endpoint	Purpose
GET	/api/v1/kafka/topics	List topics
GET	/api/v1/kafka/topics/{name}	Get topic details
POST	/api/v1/kafka/topics	Create topic
DELETE	/api/v1/kafka/topics/{name}	Delete topic
GET	/api/v1/kafka/topics/{name}/messages	Browse messages
GET	/api/v1/kafka/consumer-groups	List consumer groups
GET	/api/v1/kafka/consumer-groups/{id}	Group details

Cache API :50035

Method	Endpoint	Purpose
GET	/api/v1/health	Health check
GET	/api/v1/server/info	Server info
GET	/api/v1/keys/scan	Browse keys by pattern
GET	/api/v1/keys/{key}	Get key value
PUT	/api/v1/keys/{key}	Set key value
DELETE	/api/v1/keys/{key}	Delete key
PUT	/api/v1/keys/{key}/expire	Set TTL
PUT	/api/v1/keys/{key}/rename	Rename key
DELETE	/api/v1/keys/bulk-delete	Bulk delete

Observability API :50010

Method	Endpoint	Purpose
POST	/api/v1/ws/ticket	Obtain WebSocket ticket
GET	/api/v1/dashboard/metrics	Dashboard metrics
GET	/api/v1/logs/query	Query logs
GET	/api/v1/traces/query	Query traces

Approval Workflow API

Method	Endpoint	Purpose
GET	/api/v1/workflows	List workflows
GET	/api/v1/workflows/{id}	Get workflow
POST	/api/v1/workflows	Create workflow
PUT	/api/v1/workflows/{id}	Update workflow
DELETE	/api/v1/workflows/{id}	Delete workflow
GET	/api/v1/workflows/{id}/versions	List versions
POST	/api/v1/workflows/{id}/versions	Create version
GET	/api/v1/workflows/{id}/instances	List instances
GET	/api/v1/tasks	List user tasks
GET	/api/v1/tasks/{id}	Get task details
POST	/api/v1/tasks/{id}/claim	Claim task
POST	/api/v1/tasks/{id}/complete	Complete task
POST	/api/v1/tasks/{id}/delegate	Delegate task

Access Management API

Method	Endpoint	Purpose
GET	/api/v1/users	List users
GET	/api/v1/users/{id}	Get user
POST	/api/v1/users	Create user
PUT	/api/v1/users/{id}	Update user
DELETE	/api/v1/users/{id}	Delete user
GET	/api/v1/roles	List roles
GET	/api/v1/roles/{id}	Get role
POST	/api/v1/roles	Create role
PUT	/api/v1/roles/{id}	Update role
GET	/api/v1/groups	List groups
POST	/api/v1/groups	Create group

Validation API

Method	Endpoint	Purpose
POST	/api/v1/validate/sdg-source	Validate SDG source config

---

WebSocket

Used for real-time observability streaming:

---

Error Handling

class ApiError extends Error {
  status: number;
  fieldErrors: FieldError[];      // { field, code, message }
  isValidationError: boolean;     // true for 422
}

• Global: RouteErrorPage as errorElement on all routes
• Component-level: ErrorBoundary for React render errors
• API-level: Each service handles errors via toast notifications (Sonner)