Web UI

The Barbacane Control Plane includes a React-based web interface for managing your API gateway. This guide covers the features and workflows available in the UI.

Getting Started

Starting the UI

# Using Makefile (from project root)
make ui

# Or manually
cd ui && npm run dev

The UI runs at http://localhost:5173 and proxies API requests to the control plane at http://localhost:9090.

Prerequisites

Before using the UI, ensure:

Control Plane is running - Start with make control-plane
Database is ready - Start PostgreSQL with make db-up
Plugins are seeded - Run make seed-plugins to populate the plugin registry

Features Overview

Feature	Description
Projects	Create and manage API gateway projects
Specs	Upload and manage OpenAPI/AsyncAPI specifications
Plugin Registry	Browse available plugins with schemas
Plugin Configuration	Configure plugins per project with validation
Builds	Compile specs into deployable artifacts
Deploy	Deploy artifacts to connected data planes
API Keys	Manage authentication for data planes

Projects

Projects organize your API gateway configuration. Each project contains:

Specs - API specifications to compile
Plugins - Configured middleware and dispatchers
Builds - Compilation history and artifacts
Data Planes - Connected gateway instances

Creating a Project

Navigate to Projects from the sidebar
Click New Project
Enter a name and optional description
Click Create

You can also create a project from a template by clicking From Template, which uses the /init endpoint to generate a starter API specification.

Each project has a tabbed interface:

Tab	Description
Specs	Manage API specifications for this project
Plugins	Configure which plugins to use and their settings
Builds	View compilation history and trigger new builds
Deploy	Deploy artifacts and manage connected data planes
Settings	Project settings and danger zone

Specs Management

Uploading Specs

Navigate to a project’s Specs tab
Click Upload Spec
Select an OpenAPI or AsyncAPI YAML/JSON file
The spec is parsed, validated, and stored

Spec Features

Revision History - Each upload creates a new revision
Content Preview - View the raw spec content
Validation - Specs are validated on upload
Type Detection - Automatically detects OpenAPI vs AsyncAPI

Global Specs View

The Specs page in the sidebar shows all specs across all projects. Use this for:

Browsing all uploaded specifications
Searching specs by name
Viewing specs not yet assigned to projects

Plugin Registry

The Plugin Registry shows all available WASM plugins:

Plugin Types

Type	Description
Middleware	Request/response processing (auth, rate limiting, CORS)
Dispatcher	Backend integration (HTTP upstream, Lambda, mock)

Plugin Information

Each plugin displays:

Name and Version - Unique identifier
Description - What the plugin does
Capabilities - Required host functions (e.g., http, log, kv)
Config Schema - JSON Schema for configuration (if defined)

Deleting Plugins

Plugins can be deleted from the registry if they’re not in use by any project. If a plugin is in use, you’ll see an error message asking you to remove it from all projects first.

Plugin Configuration

Configure plugins for each project from the Plugins tab.

Adding a Plugin

Click Add Plugin
Select a plugin from the registry dropdown
The plugin’s JSON Schema (if available) generates a configuration form
Fill in required and optional fields
Click Add Plugin

Configuration Features

Schema-based forms - Auto-generated from JSON Schema
Real-time validation - Invalid configs are rejected before save
Enable/Disable - Toggle plugins without removing configuration
Reorder - Drag to change middleware execution order

Example: Configuring Rate Limiting

Add the rate-limit plugin
Configure:
- quota: Maximum requests per window (e.g., 1000)
- window: Time window in seconds (e.g., 60)
Save the configuration

Example: Configuring CORS

Add the cors plugin
Configure:
- allowed_origins: Array of allowed origins (e.g., ["https://example.com"])
- allowed_methods: HTTP methods (e.g., ["GET", "POST", "OPTIONS"])
- max_age: Preflight cache duration in seconds
Save the configuration

Builds

Compile your specs and plugins into deployable .bca artifacts.

Triggering a Build

Navigate to a project’s Builds tab
Click Build
Watch the compilation progress
Download the artifact when complete

Build Status

Status	Description
Pending	Build queued
Compiling	Compilation in progress
Succeeded	Artifact ready for download/deploy
Failed	Check error details for issues

Build Errors

Common build errors:

Missing dispatcher - Operation has no x-barbacane-dispatch
Invalid config - Plugin configuration doesn’t match schema
Plugin not found - Referenced plugin not in registry
HTTP URL rejected - Use HTTPS for production builds

Deploy

Deploy artifacts to connected data planes for zero-downtime updates.

Connecting Data Planes

Data planes connect to the control plane via WebSocket:

barbacane serve \
  --control-plane ws://localhost:9090/ws/data-plane \
  --project-id <project-uuid> \
  --api-key <api-key>

Connected data planes appear in the Deploy tab with status indicators:

Status	Description
Online	Connected and receiving updates
Deploying	Currently loading new artifact
Offline	Not connected

Creating API Keys

Navigate to a project’s Deploy tab
Click Create Key in the API Keys section
Enter a descriptive name
Copy the key immediately - it’s only shown once

Deploying an Artifact

Ensure at least one data plane is connected
Click Deploy Latest
The control plane notifies all connected data planes
Data planes download, verify, and hot-reload the artifact

Project Templates

Create new projects from templates using the Init page:

Available Templates

Template	Description
Basic	Minimal OpenAPI spec with health endpoint
Auth	Includes JWT authentication middleware
Full	Complete example with auth, rate limiting, and CORS