Implementation:ArroyoSystems Arroyo Rest Router

Field	Value
Sources	ArroyoSystems/arroyo
Domains	Stream_Processing, API_Infrastructure
Last Updated	2026-02-08

Overview

Rest_Router defines the Axum router, application state, and static asset serving for the Arroyo REST API, combining all API endpoint routes under /api/v1/ with an embedded web console and Swagger UI documentation.

Description

The crates/arroyo-api/src/rest.rs module is the central routing hub of the Arroyo API server. It assembles all REST endpoint handlers into a unified Axum Router and serves the embedded web UI as a single-page application.

Application State

The AppState struct holds shared state passed to all route handlers via Axum's state extraction:

• database: DatabaseSource -- The PostgreSQL connection pool used by all handlers for query execution.

Router Construction

The create_rest_app function builds the complete application router with the following structure:

CORS configuration: A permissive CORS layer allowing all origins, methods, and headers (intended for development; noted with a TODO for production restriction).

Job sub-routes (nested under /pipelines/:id/jobs):

• GET / -- List pipeline jobs (get_pipeline_jobs)
• GET /:job_id/errors -- Job error logs (get_job_errors)
• GET /:job_id/checkpoints -- Job checkpoints (get_job_checkpoints)
• GET /:job_id/checkpoints/:checkpoint_id/operator_checkpoint_groups -- Checkpoint details (get_checkpoint_details)
• GET /:job_id/output -- SSE output stream (get_job_output)
• GET /:job_id/operator_metric_groups -- Job metrics (get_operator_metric_groups)

API routes (under /api/v1):

• GET /ping -- Health check
• GET /connectors -- List connectors
• POST /connection_profiles/test -- Test a connection profile
• POST /connection_profiles -- Create a connection profile
• GET /connection_profiles -- List connection profiles
• DELETE /connection_profiles/:id -- Delete a connection profile
• GET /connection_profiles/:id/autocomplete -- Connection profile autocomplete
• GET /connection_tables -- List connection tables
• POST /connection_tables -- Create a connection table
• POST /connection_tables/test -- Test a connection table
• POST /connection_tables/schemas/test -- Test a schema
• DELETE /connection_tables/:id -- Delete a connection table
• POST /udfs -- Create a UDF
• GET /udfs -- List UDFs
• POST /udfs/validate -- Validate a UDF
• DELETE /udfs/:id -- Delete a UDF
• POST /pipelines -- Create a pipeline
• POST /pipelines/preview -- Create a preview pipeline
• GET /pipelines -- List pipelines
• GET /jobs -- List all jobs
• POST /pipelines/validate_query -- Validate SQL query
• PATCH /pipelines/:id -- Update a pipeline
• GET /pipelines/:id -- Get a pipeline
• POST /pipelines/:id/restart -- Restart a pipeline
• DELETE /pipelines/:id -- Delete a pipeline

Top-level routes:

• Swagger UI at /api/v1/swagger-ui serving the OpenAPI specification
• Static file handler as fallback for all non-API routes

Embedded Web UI

The Assets struct uses rust_embed to embed the compiled web UI from ../../webui/dist directly into the binary. The static file serving works as follows:

• static_handler matches incoming URIs against embedded assets, serving them with appropriate MIME types via mime_guess.
• Requests for paths without file extensions (e.g., /pipelines/details) are treated as SPA routes and served the index.html fallback.
• index_html performs template variable substitution in index.html, replacing placeholders for Template:API ENDPOINT, Template:CLUSTER ID, Template:DISABLE TELEMETRY, and Template:BASENAME with runtime configuration values.
• The x-arroyo-basename custom header controls the base path prefix for asset URLs, enabling reverse proxy deployments.

Health Check

The ping endpoint returns a simple Json("Pong") response, useful for health checks and connectivity verification.

Fallback Handling

• api_fallback returns a 404 ErrorResp for unmatched API routes under /api/v1/.
• not_found_static returns a plain text 404 for unmatched static asset requests.

Usage

The create_rest_app function is called by start_server in lib.rs to construct the application router before applying compression and authentication layers. The resulting router serves both the REST API and the web console from a single HTTP server.

Code Reference

Source Location

Repository

ArroyoSystems/arroyo (GitHub)

File

crates/arroyo-api/src/rest.rs

Lines

L1--L193

Signature

/// Application state shared across all Axum handlers.
#[derive(Clone)]
pub struct AppState {
    pub(crate) database: DatabaseSource,
}

/// Build the complete Axum router with API routes, Swagger UI, and static assets.
pub fn create_rest_app(database: DatabaseSource) -> Router

/// Health check endpoint: GET /v1/ping
pub async fn ping() -> impl IntoResponse

/// Fallback for unmatched API routes, returns 404.
pub async fn api_fallback() -> impl IntoResponse

Import

use arroyo_api::rest::{AppState, create_rest_app, ping};

I/O Contract

Inputs (create_rest_app)

Name	Type	Required	Description
database	DatabaseSource	Yes	PostgreSQL connection pool to be shared with all handlers

Outputs (create_rest_app)

Name	Type	Description
return	Router	Fully configured Axum router with API routes, Swagger UI, static assets, CORS, and state

Route Summary

Method	Path	Handler	Description
GET	/api/v1/ping	ping	Health check
GET	/api/v1/pipelines	get_pipelines	List all pipelines
POST	/api/v1/pipelines	create_pipeline	Create a pipeline
GET	/api/v1/jobs	get_jobs	List all jobs
GET	/api/v1/connectors	get_connectors	List all connectors
*	/api/v1/swagger-ui	SwaggerUi	Interactive API documentation
GET	/*	static_handler	Embedded web UI assets and SPA fallback

Usage Examples

Creating the Application Router

use arroyo_api::rest::create_rest_app;
use cornucopia_async::DatabaseSource;

let database = DatabaseSource::new(pool);
let app = create_rest_app(database);

// Apply additional middleware layers
let app = app.layer(CompressionLayer::new());

// Serve the application
axum::serve(listener, app.into_make_service()).await?;

Health Check Request

curl http://localhost:8000/api/v1/ping
# Response: "Pong"

Accessing the Swagger UI

# Open in browser:
# http://localhost:8000/api/v1/swagger-ui

Related Pages

• Principle:ArroyoSystems_Arroyo_API_Architecture
• Implementation:ArroyoSystems_Arroyo_Api_Server
• Implementation:ArroyoSystems_Arroyo_Jobs_Api
• Implementation:ArroyoSystems_Arroyo_Metrics_Endpoint
• Implementation:ArroyoSystems_Arroyo_Get_Connectors
• Implementation:ArroyoSystems_Arroyo_Create_Pipeline_Int