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 {} } }
stateis the application state, cloned into every call. Make it cheap to clone, such as anArc.inputis the deserialized request body.headersis a struct whose fields are the request headers the route reads, named by their serde names, in lowercase. Usereflectapi::Emptyfor none. See Request Headers.Ris either the output, for a route that cannot fail, orResult<Output, Error>. These are the two formsIntoResultaccepts. The error type implementsStatusCode, 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:
- axum:
reflectapi::axum::into_routerturns them into anaxum::Router. - Cloudflare Workers and celld: a small adapter over the dispatcher.
- Any other server:
reflectapi::dispatch::Dispatcherroutes a request to its handler and returns the response to send.
All of them serve the same wire format.