#Quickstart — Build Your First API in 5 Minutes

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

Build your first type-safe HTTP API with Ranvier. This guide takes less than 5 minutes to complete.

#Prerequisites

Rust toolchain 1.85+ (with edition = "2024" support)
cargo package manager

If you don't have Rust installed, get it from rustup.rs.

rustc --version  # Verify 1.85.0 or later

#Step 1: Create a Project

cargo init my-api
cd my-api

Add the following dependencies to your Cargo.toml:

[package]
name = "my-api"
version = "0.1.0"
edition = "2024"

[dependencies]
ranvier = "0.33"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

The single ranvier facade crate gives you access to all 10 workspace crates — core, macros, runtime, http, and more.

#Step 2: Write a Hello Transition

Replace src/main.rs with the following code:

use ranvier::prelude::*;
use serde_json::json;

/// A simple transition that returns a JSON response
#[transition]
async fn hello(
    _state: (),
    _resources: &(),
    _bus: &mut Bus,
) -> Outcome<serde_json::Value, String> {
    Outcome::Next(json!({
        "message": "Hello from Ranvier!",
        "version": "0.33.0"
    }))
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt::init();

    // Axon::simple — same-type input/output pipeline
    let axon = Axon::simple::<serde_json::Value>("hello")
        .then(hello);

    tracing::info!("Ranvier server starting on http://127.0.0.1:3000");

    Ranvier::http()
        .bind("127.0.0.1:3000")
        .route("/api/hello", axon)
        .run(())
        .await?;

    Ok(())
}

#Code Walkthrough

Element	Purpose
`#[transition]`	Macro that converts an async function into a Ranvier Transition
`Outcome::Next(T)`	Returns a success result and advances to the next node
`Axon::simple::<T>(label)`	Convenience constructor for a same-type (`T → T`) pipeline
`Bus`	Type-safe dependency injection container
`Ranvier::http()`	HTTP Ingress builder with routing and middleware support

#Step 3: Run the Server

cargo run

Output:

INFO my_api: Ranvier server starting on http://127.0.0.1:3000

#Step 4: Test the API

In a new terminal:

curl http://localhost:3000/api/hello

Response:

{
  "message": "Hello from Ranvier!",
  "version": "0.33.0"
}

#Core Concepts

Concept	Description
Transition	A unit of business logic, implemented via the `#[transition]` macro or the `Transition` trait
Axon	An execution pipeline that chains Transitions together
Outcome	The result type of a Transition — `Next`, `Fault`, `Branch`, `Jump`, `Emit`
Bus	A type-safe shared state container (`insert`, `read`, `get`, `require`)
Schematic	An execution graph structure auto-generated from an Axon

#Next Steps

Hello World — Build a Transition and Axon pipeline from scratch
Tutorial: TODO API — Build a complete REST API with JWT auth, CRUD, and guards
Bus Access Patterns — Decision tree for read(), get(), require(), try_require() methods
Production Readiness Checklist — Pre-deployment checklist

Getting Started Guide — Complete onboarding guide covering concepts, setup, and your first project
Security Hardening — SQL injection prevention, timing-safe authentication
Pattern Catalog — Reusable patterns including sagas, fan-out/fan-in, and more