Hi all! I'd like to share reflectapi, a library we built at Partly and use in production, and I'd love your feedback on it.

You write your API as plain Rust functions with serde types. reflectapi turns them into a schema and generates TypeScript, Python and Rust clients, where every route is the same typed function: its input, output, errors and streamed events.

A route:

use reflectapi::{Builder, Empty, Input, Output}; use serde::{Deserialize, Serialize}; #[derive(Deserialize, Input)] struct CreateUser { name: String, email: String } #[derive(Serialize, Output)] struct User { id: u32, name: String, email: String } 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()?; 

And the generated TypeScript client:

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); } 

A route can also stream typed events over Server-Sent Events:

#[derive(Serialize, Output)] #[serde(tag = "type")] enum UserEvent { Created { id: u32, name: String }, Deleted { id: u32 }, } async fn user_events(_: (), _: Empty, _: Empty) -> Result<impl Stream<Item = UserEvent>, Infallible> { Ok(stream::iter([UserEvent::Deleted { id: 1 }])) } // registered with .stream_route(user_events, |r| r.name("users.events")) 

Each client reads it as a typed stream, and TypeScript narrows each event by its tag:

const events = await api.users.events({}, {}); if (events.is_ok()) { for await (const event of events.unwrap_ok()) { switch (event.type) { case "Created": console.log(event.name); break; case "Deleted": console.log(event.id); break; } } } 

What reaches the clients:

  • Your types as they are: generics, enums with data, fields that can be absent or null, and serde's attributes.
  • Typed errors: a route's error enum sets each response's status code, and every client matches on it. A missed variant is a compile error in TypeScript and Rust.
  • Typed streams in every client: an async iterator in TypeScript and Python, a Stream in Rust.
  • Deprecations that show up in the editor, and an OpenAPI document for other languages and tools.

More examples, in all three languages: Type fidelity.

It serves with axum in one call, on Cloudflare Workers, or on any HTTP server through a framework-free dispatcher.

Links:

I'd especially value your thoughts on:

  1. The Quick start: if you try it, where did you get stuck or confused?
  2. The route model: routes are named calls (users.create) rather than REST resources. Does that fit how you build APIs, or is it a deal-breaker?
  3. What's missing that would stop you using it: a client language, a framework, a feature?

Thanks for reading!

1 post - 1 participant

Read full topic