reflectapi
Open source · Built and used in production at

Reflect your Rust API into the world

Define your web API in Rust, generate typed TypeScript, Python and Rust clients, typed streams included. Serve it with Axum, Cloudflare Workers or any HTTP server.

From Rust to typed clients

Your Rust code is the contract

Each Rust route reaches every client as the same typed function: input, output, errors and streamed events.

  1. 01

    Derive

    reflectapi::Input or reflectapi::Output beside serde's derives.

  2. 02

    Route

    Plain async handlers, named on a Builder that gives the schema and the routes.

  3. 03

    Generate

    reflectapi codegen writes the clients from the schema.

  4. 04

    Call

    Typed functions, in TypeScript, Python or Rust.

Server: Rust
use reflectapi::{Builder, Empty, Input, Output};
use serde::{Deserialize, Serialize};

// 01 Derive
#[derive(Deserialize, Input)]
struct CreateUser { name: String, email: String }

#[derive(Serialize, Output)]
struct User { id: u32, name: String, email: String }

// 02 Route
async fn create_user(
    _: (), req: CreateUser, _: Empty,
) -> User {
    User { id: 1, name: req.name, email: req.email }
}

let (schema, routers) = Builder::new()
    .route(create_user, |r| r.name("users.create"))
    .build()?;
Generated client:
// 04 Call
import { client } from "./generated";

const api = client("https://api.example.com");
const result = await api.users.create(
  { name: "Ada", email: "ada@example.com" },
  {},
);
if (result.is_ok()) {
  console.log(result.unwrap_ok().id);
}

Serve the routes with axum in one call, on Cloudflare Workers, or from any HTTP server. How it works, in detail

Type fidelity

Generated clients as precise as your Rust types

Errors are types too

A route's error enum chooses each response's status, and every client gets it as a typed value to match on, kept apart from network failures. Errors

Rust
#[derive(Serialize, Output, StatusCode)]
enum CreateUserError {
    #[reflectapi(status = 409)]
    EmailTaken,
    #[reflectapi(status = 422)]
    InvalidEmail { reason: String },
}
// async fn create_user(...)
//     -> Result<User, CreateUserError>
const error = result.unwrap_err().err();
if (error !== undefined) {
  console.log(match(error, {
    EmailTaken: () => "taken",
    InvalidEmail: ({ reason }) => reason,
  }));
}
// Leave out a variant: a type error.

Generics

A generic type stays generic in every client, Python and Rust included, instead of one copy per use. Types

Rust
#[derive(Serialize, Output)]
struct Page<T> {
    items: Vec<T>,
    cursor: Option<String>,
}
// users.list returns Page<User>
export interface Page<T> {
    items: Array<T>,
    cursor: (string | null),
}
// users.list gives
// AsyncResult<Page<User>, {}>

Enums with data

serde's tagging styles become discriminated unions, so the client narrows on the tag. Enums

Rust
#[derive(Serialize, Output)]
#[serde(tag = "type")]
enum Shape {
    Circle { radius: f64 },
    Rect { w: f64, h: f64 },
}
export type Shape =
  | { type: "Circle", radius: number }
  | { type: "Rect", w: number, h: number }

Absent, null or a value

For partial updates, reflectapi::Option tells "not sent" from "set to null", and the clients keep all three states. Option

Rust
#[derive(Deserialize, Input)]
struct UserPatch {
    #[serde(default)]
    nickname: reflectapi::Option<String>,
}
export interface UserPatch {
    nickname?: (string | null | undefined),
}

Deprecations reach the editor

A deprecated field or route is marked in every client, so editors strike it through. A deprecated response field also turns optional, ready for its removal. Deprecations

Rust
#[derive(Serialize, Output)]
struct Profile {
    #[deprecated(note = "Use display_name.")]
    nickname: String,
    display_name: String,
}
export interface Profile {
    /** @deprecated Use display_name. */
    nickname?: string,
    display_name: string,
}

And more

The rest of what a Rust type says reaches the clients too.

Conference talk · Rust Forge 2025 · Wellington

Reflect your Rust API into the world

Why reflectapi exists, why client generation through OpenAPI kept failing, and a live demo of a server change turning into a compile error in its client.

Watch the talk

Get started

The crate, for the server
$ cargo add reflectapi --features builder,axum
The CLI, for the clients
$ cargo binstall reflectapi-cli