Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

How It Works

reflectapi treats an API as a set of named calls. Each call has:

  • a name, such as users.get;
  • an input: the request body;
  • an output: the response body;
  • an error: the response body when the call fails, sent with an HTTP status the error chooses;
  • headers: the request headers the call reads.

Everything else follows from these five. The URL path is the name, the method is POST, and the status says whether the body is the output or the error (On the Wire has the details). A generated client needs no more than that, so each route becomes a typed function: client.users.get(input, headers), returning the output or the error.

The flow

flowchart TD
  types["Types<br/>#35;[derive(Input, Output)]"] --> route["Builder::route"]
  handlers["Handlers<br/>async fn(state, input, headers)"] --> route
  route --> build[".build()"]
  build --> schema["Schema<br/>reflectapi.json"]
  build --> routers["Routers<br/>Vec#lt;Router#lt;S#gt;#gt;"]
  schema --> codegen["reflectapi codegen CLI<br/>or reflectapi::codegen"]
  codegen --> clients["TypeScript, Rust and Python clients<br/>OpenAPI document"]
  routers --> adapter["reflectapi::axum::into_router<br/>or reflectapi::dispatch::Dispatcher"]
  adapter --> server["HTTP server"]
  clients -. "call over HTTP" .-> server

One definition produces both sides: the schema, from which the clients are generated, and the routers that serve the routes. Both come from the same Rust types and handlers, so a client generated from the current schema matches the server.

Types

A type the server reads (a request body or request headers) derives Input next to serde's Deserialize. A type it writes (a response, an error, a stream item or response headers) derives Output next to Serialize. A type used both ways derives all four.

The derives read serde's attributes (rename, tag, flatten, default, skip_serializing_if and the rest), so the schema describes what serde actually reads and writes. Doc comments on types, fields and variants are carried into the generated clients.

A type is reflected separately as input and as output, because serde can treat the two directions differently. A field with #[serde(default)] is optional in a request; a field with #[serde(skip_serializing_if = "...")] may be missing from a response. The Attributes reference lists what reflectapi adds on top of serde.

Primitives, String, Option, Vec, maps, tuples and many library types (chrono, uuid, url and others, behind crate features) already implement both traits. reflectapi::Empty stands for "nothing": no input, no headers or no output. Types covers what can cross the API and how to bring in a type reflectapi doesn't know.

Handlers

A handler is an async function of three arguments:

#![allow(unused)]
fn main() {
type S = ();
type I = reflectapi::Empty;
type H = reflectapi::Empty;
type R = reflectapi::Empty;
async fn handler(state: S, input: I, headers: H) -> R
{ reflectapi::Empty {} }
}
  • state is the application state, cloned into every call. Make it cheap to clone, such as an Arc.
  • input is the deserialized request body.
  • headers is a struct whose fields are the request headers the route reads, named by their serde names, in lowercase. Use reflectapi::Empty for none. See Request Headers.
  • R is either the output, for a route that cannot fail, or Result<Output, Error>. These are the two forms IntoResult accepts. The error type implements StatusCode, which gives the HTTP status of its response. See Errors.

The handler must be Copy, Send and Sync, and its future Send: an async fn item works, as does a closure that captures nothing. Anything else it needs comes in through state.

A stream route's handler has the same arguments and returns Result<impl Stream<Item = T>, Error>. It is registered with Builder::stream_route and served as Server-Sent Events (Streaming Endpoints).

The builder

Builder collects the routes. Each route call takes a handler and a function that configures it through a RouteBuilder: its name, description, whether it is readonly, its tags and its deprecation. The configuration function is a plain fn, so its closure cannot capture variables.

#![allow(unused)]
fn main() {
use reflectapi::{Builder, Empty, Input, Output};
use serde::{Deserialize, Serialize};

/// A user of the system.
#[derive(Serialize, Output)]
struct User {
    id: u32,
    name: String,
}

#[derive(Deserialize, Input)]
struct GetUserRequest {
    id: u32,
}

#[derive(Serialize, Output, reflectapi::StatusCode)]
enum GetUserError {
    /// No user has this id.
    #[reflectapi(status = 404)]
    NotFound,
}

#[derive(Deserialize, Input)]
struct AuthHeaders {
    authorization: String,
}

async fn get_user(
    _state: (),
    request: GetUserRequest,
    _headers: AuthHeaders,
) -> Result<User, GetUserError> {
    match request.id {
        1 => Ok(User { id: 1, name: "Alice".into() }),
        _ => Err(GetUserError::NotFound),
    }
}

async fn health_check(_state: (), _input: Empty, _headers: Empty) -> Empty {
    Empty {}
}

let (schema, routers) = Builder::new()
    .name("Users")
    .route(get_user, |b| {
        b.name("users.get")
            .description("Get a user by id")
            .readonly(true)
    })
    .route(health_check, |b| b.name("health.check"))
    .build()
    .expect("a valid API");

let names: Vec<&str> = schema.functions().map(|f| f.name()).collect();
assert_eq!(names, ["users.get", "health.check"]);

let get = schema.functions().next().unwrap();
assert!(get.readonly());
assert!(get.error_type.is_some());
assert!(get.input_headers().is_some());

// A route that can't fail has no error type, and `Empty` is no input.
let health = schema.functions().nth(1).unwrap();
assert!(health.error_type.is_none());
assert!(health.input_type().is_none());

// One router per builder; `extend` and `nest` add more.
assert_eq!(routers.len(), 1);
}

build() checks the definition and returns the schema and the routers, or every problem it found as BuildErrors. A server that doesn't need the schema at runtime can build the routers alone; see build modes.

A readonly route is served on GET as well as POST. The schema records the flag, but the generated clients call every route with POST.

A larger API is split across several builders, combined with Builder::nest and Builder::extend, and can sit under a base path set with Builder::path, which applies to the routes added after it. See Organising a Larger API.

Names become namespaces

The route name is both the URL path and the client function. Dots split it into namespaces: users.get is client.users.get(...) in TypeScript, Python and Rust, and admin.users.get nests one level deeper. A - in a name becomes _ in the clients, so pets.get-first is client.pets.get_first(...).

The schema

The schema is the API without the code: the routes, with their names, descriptions and flags, and every type they use. It serializes to JSON, and is usually written to a reflectapi.json file:

fn main() -> Result<(), Box<dyn std::error::Error>> {
let (schema, _) = reflectapi::Builder::<()>::new().build()?;
std::fs::write("reflectapi.json", serde_json::to_string_pretty(&schema)?)?;
Ok(())
}

The reflectapi CLI generates clients from that file:

reflectapi codegen --language typescript --schema reflectapi.json --output clients/typescript/

The same generators are available in Rust as reflectapi::codegen, behind the codegen feature, for generating clients from a build step or a test without the CLI (example). Generated Clients describes each language's output, and Keep the client in sync how to check the generated files in CI.

Serving

The routers are framework-independent. An adapter puts them on an HTTP server:

All of them serve the same wire format.