feagi-api

REST API layer for FEAGI with HTTP and ZMQ transport adapters.

Architecture Overview

feagi-api is responsible for business logic of API endpoints, while feagi-io handles transport infrastructure.

┌─────────────────────────────────────────────┐
│ feagi-api (Business Logic Layer)            │
│                                              │
│  ┌────────────────────────────────────────┐ │
│  │ endpoints/ (Transport-agnostic)        │ │
│  │  • health.rs                           │ │
│  │  • cortical_areas.rs                   │ │
│  │  • genome.rs                           │ │
│  └────────────────────────────────────────┘ │
│              ↓ Called by ↓                   │
│  ┌──────────────────┬──────────────────────┐│
│  │ HTTP (Axum)      │ ZMQ (feagi-io)      ││
│  │ transports/http/ │ transports/zmq/      ││
│  └──────────────────┴──────────────────────┘│
└─────────────────────────────────────────────┘
                     ↓
┌─────────────────────────────────────────────┐
│ feagi-io (Transport Infrastructure)        │
│  • api_control.rs (ZMQ ROUTER/DEALER)      │
│  • sensory.rs (PUSH/PULL)                   │
│  • motor.rs (PUB/SUB)                       │
│  • visualization.rs (PUB/SUB)               │
└─────────────────────────────────────────────┘

Design Principles

Clear Separation of Concerns

feagi-api:

• ✅ Defines API endpoints (what operations are available)
• ✅ Implements business logic (transport-agnostic)
• ✅ Provides thin transport adapters (HTTP + ZMQ)
• ❌ Does NOT implement ZMQ infrastructure

feagi-io:

• ✅ Owns ALL ZMQ code (data + control plane)
• ✅ Provides api_control for REST-over-ZMQ
• ✅ Handles real-time streaming (sensory, motor, viz)
• ❌ Does NOT implement business logic

Unified Endpoint Layer

All endpoints are transport-agnostic:

// src/endpoints/health.rs

pub async fn health_check(
    auth_ctx: &AuthContext,
    analytics_service: Arc<dyn AnalyticsService>,
) -> ApiResult<HealthCheckResponseV1> {
    // Business logic here - NO HTTP or ZMQ code!
}

This endpoint is called by both HTTP and ZMQ adapters:

// HTTP adapter (Axum)
async fn http_health_handler(State(state): State<ApiState>) -> Json<ApiResponse<...>> {
    endpoints::health::health_check(&auth_ctx, state.analytics).await
}

// ZMQ adapter (feagi-io integration)
async fn zmq_health_handler(state: &ZmqApiState) -> ZmqResponse {
    endpoints::health::health_check(&auth_ctx, state.analytics).await
}

Integration with feagi-io

The ZMQ transport adapter in feagi-api uses feagi-io infrastructure:

// feagi-io provides the ZMQ transport
use feagi_io::api_control::ApiControlStream;

// feagi-api provides the business logic
use feagi_api::transports::zmq::handle_api_control_request;

// In feagi-io::api_control, when a REST request arrives:
let response = handle_api_control_request(
    method,
    path,
    body,
    &api_state
).await;

Why Keep Them Separate?

API Versioning

Supports multiple API versions:

/api/v1/health      → Version 1 (stable)
/api/v2/health      → Version 2 (future)
/health             → Version-agnostic (always available)

Transport Support

HTTP (Axum)

GET  /api/v1/health          → Health check
GET  /api/v1/cortical-areas  → List cortical areas
POST /api/v1/cortical-areas  → Create cortical area

Features:

• OpenAPI 3.0 documentation (utoipa)
• Custom Swagger UI styling
• CORS support
• Request/response logging

ZMQ (via feagi-io)

Same endpoints available over ZMQ ROUTER/DEALER:

{
  "method": "GET",
  "path": "/api/v1/health",
  "body": null
}

Response:

{
  "status": 200,
  "body": {
    "success": true,
    "data": { ... },
    "timestamp": "..."
  }
}

Contract Testing

All endpoints tested for 100% compatibility with Python FastAPI:

#[test]
fn test_health_check_response_format() {
    let rust_response = rust_api.get("/v1/health").await;
    let python_snapshot = load_snapshot("health_check.json");
    
    assert_json_match!(rust_response, python_snapshot);
}

Security (Stub Architecture)

Security stubs are in place for future implementation:

// Authentication (stub - always anonymous for now)
let auth_ctx = AuthContext::anonymous();

// Authorization (stub - always allowed for now)
Authorizer::authorize(&auth_ctx, Permission::CorticalAreaRead)?;

Status

Current (Phase 1 - Infrastructure):

• ✅ Crate structure
• ✅ Common types (ApiRequest, ApiResponse, ApiError)
• ✅ Security stubs (AuthContext, Permission)
• ✅ HTTP server (Axum) with basic routing
• ✅ ZMQ server (feagi-io integration)
• ✅ Middleware (CORS, logging)
• ✅ Health endpoint (working for HTTP + ZMQ)

Next (Phase 2 - Endpoints):

• 🔄 OpenAPI/Swagger UI integration
• 🔄 Cortical area endpoints (CRUD)
• 🔄 Brain region endpoints
• 🔄 Genome endpoints
• 🔄 Analytics endpoints

Future (Phase 3 - Testing):

• ⏳ Contract tests (Python compatibility)
• ⏳ Integration tests
• ⏳ Performance benchmarks

Dependencies

feagi-services = { path = "../feagi-services" }  # Service layer
feagi-types = { path = "../feagi-types" }        # Core types
feagi-io = { path = "../feagi-io" }            # ZMQ infrastructure

axum = "0.7"              # HTTP server
utoipa = "4.0"            # OpenAPI generation
tower-http = "0.5"        # Middleware (CORS, logging)

Example Usage

Starting the HTTP API

use feagi_api::transports::http;

let state = http::ApiState {
    analytics_service: Arc::new(analytics),
};

let app = http::create_app(state);

axum::Server::bind(&"0.0.0.0:8080".parse().unwrap())
    .serve(app.into_make_service())
    .await
    .unwrap();

Integrating with feagi-io (ZMQ)

// In feagi-io::api_control when REST request arrives
use feagi_api::transports::zmq;

let api_state = zmq::ZmqApiState {
    analytics_service: Arc::new(analytics),
};

let response = zmq::handle_api_control_request(
    method,
    path,
    body,
    &api_state
).await;

// Send response back over ZMQ

License

Apache-2.0