nifi-rust-client

Idiomatic Rust client for the Apache NiFi 2.x REST API.

All NiFi REST API endpoints are generated from the official OpenAPI spec and exposed via typed resource accessor methods.

Modes

Static mode (default)

For applications built against a specific NiFi version. You get full type safety, complete IDE autocompletion, and compile-time guarantees that your code matches the NiFi API exactly.

Use this when you're building a deployment pipeline, custom processor manager, or automation tool that targets a known NiFi cluster. You move in lock-step with your NiFi version — when you upgrade NiFi, you update the feature flag.

[dependencies]
nifi-rust-client = { version = "...", features = ["nifi-2-8-0"] }

let mut client = NifiClientBuilder::new("https://nifi:8443")?.build()?;
client.login("admin", "password").await?;

// Full type safety — ProcessorEntity is v2_8_0::types::ProcessorEntity
let proc = client.processors_api().get_processor("id").await?;

Dynamic mode

For tools that talk to multiple NiFi versions. The client auto-detects the NiFi version at connect time and dispatches to the correct generated API module.

Use this when you're building a monitoring dashboard, CLI tool, or fleet management system that needs to work across NiFi clusters running different versions.

[dependencies]
nifi-rust-client = { version = "...", features = ["dynamic"] }

let mut client = NifiClientBuilder::new("https://nifi:8443")?
    .build_dynamic()
    .await?;
client.login("admin", "password").await?;

// Returns common union types — fields are Option<T>
let about = client.flow_api().get_about_info().await?;
println!("NiFi version: {:?}", about.version);

// Check what was detected
println!("Connected to NiFi {}", client.detected_version());

Trade-offs: all fields are Option<T> since not every NiFi version populates every field. Endpoints that don't exist in the connected version return NifiError::UnsupportedEndpoint.

When to use which

Creating a client

use std::time::Duration;
use nifi_rust_client::NifiClientBuilder;
use url::Url;

let mut client = NifiClientBuilder::new("https://nifi.example.com:8443")?
    .timeout(Duration::from_secs(60))
    .connect_timeout(Duration::from_secs(10))
    .proxy(Url::parse("http://proxy.internal:3128")?)
    .build()?;

client.login("admin", "password").await?;

Builder options

Authentication

login() posts credentials to /nifi-api/access/token and stores the returned JWT on the client. The token is sent as Authorization: Bearer <token> on every subsequent request.

Token management

After a successful login(), the JWT can be persisted and reused across process restarts:

// Save token after login
if let Some(token) = client.token() {
    fs::write("nifi-token.txt", token)?;
}

// Restore on the next run instead of re-authenticating
let token = fs::read_to_string("nifi-token.txt")?;
client.set_token(token);

NiFi JWTs expire after 12 hours by default (configurable server-side via nifi.security.user.login.identity.provider.expiration). An expired token causes any API call to return NifiError::Api { status: 401, .. }. Re-call login() to obtain a fresh token:

use nifi_rust_client::NifiError;

match client.flow_api().get_about_info().await {
    Err(NifiError::Api { status: 401, .. }) => {
        client.login("admin", "password").await?;
        // retry the original call
    }
    other => { other?; }
}

Automatic re-login is not built in because storing credentials on the client would keep plaintext passwords in memory for the lifetime of the process.

Logging out

logout() sends DELETE /access/logout to invalidate the token server-side and clears it locally. The local token is always cleared, even if the server returns an error (e.g. because the token had already expired):

client.logout().await?;
// client.token() is now None

Client methods

Resource accessors

All API methods are grouped into resource structs mirroring NiFi's own API grouping. Access them via the client:

client.flow_api().get_about_info().await?;
client.processors_api().get_processor("some-id").await?;
client.processgroups_api().get_process_group("root").await?;

Error handling

All methods return Result<T, NifiError>. Variants:

• NifiError::Api { status, message } — NiFi returned a non-2xx response
• NifiError::Http { source } — network or transport error
• NifiError::Auth { message } — authentication failed (e.g. bad credentials)
• NifiError::InvalidBaseUrl { source } — bad base URL passed to the builder
• NifiError::InvalidCertificate { source } — invalid CA certificate passed to the builder
• NifiError::UnsupportedVersion { detected } — dynamic mode detected a NiFi version not compiled in
• NifiError::UnsupportedEndpoint { endpoint, version } — dynamic mode: endpoint not available in the connected NiFi version

Integration test coverage

The following API groups have CRUD lifecycle tests (create → get → update → delete → verify gone):

The following API groups are not yet covered due to requiring complex setup beyond a fresh NiFi instance: