#Quickstart: Hello World API in 5 Minutes

Version: 0.33.0 Updated: 2026-03-15 Applies to: ranvier, ranvier-core, ranvier-macros, ranvier-runtime, ranvier-http Category: Getting Started

Difficulty: Beginner Time: ~5 minutes Goal: Get a Ranvier HTTP API running and returning "Hello, World!" locally.

#Prerequisites

• Rust toolchain installed (rustup, cargo)
• ranvier CLI installed: cargo install ranvier-cli

#Step 1: Create a new project (1 min)

ranvier new hello-world --template minimal
cd hello-world

This creates:

hello-world/
├── Cargo.toml
├── src/main.rs
└── README.md

#Step 2: Inspect the generated code (1 min)

Open src/main.rs. You'll see a minimal Ranvier app:

use ranvier_core::prelude::*;
use ranvier_http::prelude::*;
use ranvier_macros::transition;
use ranvier_runtime::Axon;

#[transition]
async fn greet(_input: (), _resources: &(), _bus: &mut Bus) -> Outcome<String, anyhow::Error> {
    Outcome::Next("Hello from Ranvier!".to_string())
}

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    tracing_subscriber::fmt::init();

    let hello = Axon::<(), (), anyhow::Error>::new("hello-world")
        .then(greet);

    Ranvier::http()
        .bind("127.0.0.1:3000")
        .route("/", hello)
        .run(())
        .await
        .map_err(|e| anyhow::anyhow!("Server error: {}", e))?;

    Ok(())
}

Key concepts:

• #[transition] — marks an async function as a typed Axon transition
• Outcome::Next(value) — the happy-path result of a transition
• Axon::new("label").then(fn) — builds an execution pipeline
• Ranvier::http().route("/", axon) — wires the pipeline to an HTTP route

#Step 3: Run the server (1 min)

cargo run

Expected output:

Starting server on http://127.0.0.1:3000

#Step 4: Verify (30 sec)

In a new terminal:

curl http://127.0.0.1:3000/

Expected response:

Hello from Ranvier!

✅ Success! You have a running Ranvier HTTP API.

#Step 5: Understand what happened (1 min)

HTTP GET /
    ↓
Ranvier::http() ingress
    ↓
Axon pipeline: () → greet() → String
    ↓
HTTP 200 "Hello from Ranvier!"

The Axon is a typed execution pipeline. Every step is a Transition — a pure async function with typed input/output. Bus is a side-channel for cross-cutting concerns like tracing.

#What's Next?

#Troubleshooting

ranvier: command not found
Run cargo install ranvier-cli and ensure ~/.cargo/bin is in your PATH.

Port already in use
Change the bind address: .bind("127.0.0.1:3001") in main.rs.

Compilation error
Run cargo check for a detailed error list. See FAQ for common issues.