API Service Actors

Reflow includes 6,697 pre-generated actor templates spanning 88 API services. These actors are code-generated from OpenAPI specifications and provide native workflow nodes for interacting with third-party APIs.

Overview

API actors are gated behind the api-services feature in reflow_rt, which forwards to reflow_components/api_services. Each actor maps to a single API endpoint and is registered with Zeal as a template with:

• A template ID (e.g., api_slack_send_message)
• A human-readable title (e.g., "Send Message")
• Input/output port declarations
• Required environment variables for authentication
• A brand icon and service category

Architecture

Code Generation

API actors are generated by the api_schema_gen tool which:

1. Discovers API services from OpenAPI specifications
2. Extracts endpoints, parameters, request/response schemas
3. Generates Rust actor implementations with typed ports
4. Outputs a registry module that maps template IDs to actor instances

Runtime Resolution

#![allow(unused)]
fn main() {
// Template resolution falls through from native actors to API actors
match template_id {
    "tpl_http_request" => Some(Arc::new(HttpRequestActor::new())),
    // ... native actors ...

    // Fall through to generated API actors
    #[cfg(feature = "api_services")]
    other => crate::api::api_registry::get_api_actor_for_template(other),
}
}

Template Metadata

Each API actor provides metadata for Zeal template registration:

#![allow(unused)]
fn main() {
pub struct ApiTemplateInfo {
    pub template_id: &'static str,    // e.g., "api_slack_send_message"
    pub title: &'static str,          // e.g., "Send Message"
    pub category: &'static str,       // e.g., "api"
    pub subcategory: &'static str,    // e.g., "Slack"
    pub description: &'static str,    // Endpoint description
    pub icon: &'static str,           // Brand icon name
    pub env_var: &'static str,        // e.g., "SLACK_API_KEY"
    pub inports: &'static [&'static str],
    pub outports: &'static [&'static str],
}
}

ZIP Template Registration

When connected to Zeal, all API actor templates are registered alongside native templates:

#![allow(unused)]
fn main() {
// In ZipSession::register_templates()
let api_infos = reflow_components::get_api_template_infos();
for info in api_infos {
    templates.push(NodeTemplate {
        id: info.template_id.to_string(),
        title: info.title.to_string(),
        category: info.category.to_string(),
        subcategory: Some(info.subcategory.to_string()),
        icon: info.icon.to_string(),
        runtime: Some(RuntimeRequirements {
            executor: "reflow".to_string(),
            required_env_vars: Some(vec![info.env_var.to_string()]),
            // ...
        }),
        // ...
    });
}
}

This registers all 6,697 actors with Zeal in a single batch request.

Services

The 88 supported API services include (non-exhaustive):

Each service generates multiple actors corresponding to its API endpoints.

Feature Flag

The api-services feature controls compilation of all generated API modules. Leaving it disabled reduces compile times for applications that do not need API-service actors:

# Server build with API actors
cargo build -p reflow_server --features api_services

# Fast test build without API actors
cargo test -p reflow_server --no-default-features

When disabled, stub types ensure the rest of the codebase compiles:

#![allow(unused)]
fn main() {
#[cfg(not(feature = "api_services"))]
pub fn get_api_template_infos() -> &'static [ApiTemplateInfo] { &[] }

#[cfg(not(feature = "api_services"))]
pub fn get_api_actor_for_template(_: &str) -> Option<Arc<dyn Actor>> { None }
}

Next Steps

• Standard Component Library - Native actor reference
• Zeal IDE Integration - Template registration and event streaming