Principle:ArroyoSystems Arroyo API Architecture
Metadata
| Field | Value |
|---|---|
| Page Type | Principle |
| Knowledge Sources | Repo (ArroyoSystems/arroyo), Doc (Arroyo Documentation) |
| Domains | Stream_Processing, API_Infrastructure |
| Last Updated | 2026-02-08 |
Overview
The architectural design of Arroyo's REST API layer, encompassing server initialization, route organization, authentication, OpenAPI specification generation, and embedded web UI serving within a single HTTP/HTTPS server process.
Description
Arroyo's API architecture follows a layered design where a single HTTP server process serves both the REST API and an embedded single-page web application. The architecture addresses several concerns:
Server Infrastructure
The API server is built on Axum, an async web framework for Rust. Server initialization handles TLS configuration (optional HTTPS via rustls), zstd response compression (with SSE streams excluded), and authentication middleware (optional static API key bearer token validation). The server binds to a configurable address and port and integrates with the graceful shutdown framework.
Route Organization
All REST endpoints are organized under the /api/v1/ prefix and grouped by resource type: pipelines, jobs, connections (profiles and tables), connectors, UDFs, and metrics. Job-related sub-routes are nested under their parent pipeline resource. The routing module serves as the central hub connecting endpoint handlers to URL patterns.
OpenAPI Specification
The API uses utoipa to generate a complete OpenAPI 3.0 specification at compile time. This specification declares all endpoint paths and over 60 schema components. A Swagger UI is served at /api/v1/swagger-ui for interactive API exploration. The same OpenAPI spec is used to generate the TypeScript client types consumed by the web UI.
Authentication and Authorization
Authentication context (AuthData) carries user identity, organization membership, role, and per-organization resource limits through all handler calls. Resource limits control maximum parallelism, operator count, running jobs, and connector throughput rates.
Embedded Web Console
The compiled React web UI is embedded directly into the server binary using rust_embed. Non-API requests are served from this embedded asset store with SPA-style routing (all non-file paths serve index.html). Template variables in the HTML are substituted at serve time for runtime configuration.
Usage
API architecture principles are applied when:
- Adding new REST endpoints: New handlers follow the established pattern of Axum extractors, authentication, database interaction, and structured JSON responses.
- Modifying authentication: Changes to the authentication model must flow through the
AuthDatacontext and respect organization resource limits. - Updating the OpenAPI spec: New endpoints and types must be registered in the
utoipaspecification for client code generation. - Deploying behind reverse proxies: The
x-arroyo-basenameheader and template variable system support path-prefix deployments.