Types
A type can cross the API when it implements
Input, for
values the server reads, or
Output, for
values it writes. Your own types derive them next to serde's derives.
reflectapi implements them for the standard types below and, behind crate
features, for common library types. This page covers what can be used, how it
appears in the generated clients, and what to do with a type reflectapi
doesn't know.
Your own types
Structs and enums derive Input, Output or both. The derives read serde's
attributes, so the schema describes the JSON serde reads and writes.
mod model { use serde::Serialize; /// One page of a list. #[derive(Serialize, reflectapi::Output)] pub struct Page<T> { pub items: Vec<T>, pub next_cursor: Option<String>, } #[derive(Serialize, reflectapi::Output)] pub struct Pet { pub name: String, } } async fn pets_list( _: (), _: reflectapi::Empty, _: reflectapi::Empty, ) -> model::Page<model::Pet> { model::Page { items: vec![], next_cursor: None } } fn main() -> Result<(), reflectapi::BuildErrors> { let (schema, _) = reflectapi::Builder::new() .route(pets_list, |b| b.name("pets.list")) .build()?; // Types are named by their Rust module path. let page = schema .output_types() .types() .find(|t| t.name().ends_with("::model::Page")) .unwrap(); assert_eq!(page.parameters().map(|p| p.name()).collect::<Vec<_>>(), ["T"]); Ok(()) }
- Generic types stay generic: the clients get
Page<T>(Page[T]in Python), used asPage<Pet>. The derive bounds each type parameter byInputorOutput. It doesn't support lifetime or const generic parameters. - A type's name in the schema is its Rust module path and name, such as
my_api::model::Pet. The module path becomes a namespace in each client:my_api.model.Petin TypeScript,types::my_api::model::Petin Rust and theapi_client.my_api.modelpackage in Python. Organising a Larger API shows how to rename them. - Doc comments on types, fields and variants are carried into the clients.
Standard types
| Rust | TypeScript |
|---|---|
u8 to u128, i8 to i128, usize, isize, NonZeroU8 to NonZeroU128 | number |
f32, f64 | number |
bool | boolean |
String, char, PathBuf; &'static str as output only | string |
Option<T> | T | null |
Vec<T>, HashSet<T>, BTreeSet<T> | Array<T> |
[T; N] | FixedSizeArray<T, N>, an array of length N |
HashMap<K, V>, BTreeMap<K, V> | Record<K, V> |
| tuples of 1 to 12 elements | [A, B, ...] |
() | null |
Box<T>, Arc<T> (with serde's rc feature), Cell<T>, RefCell<T>, Mutex<T>, RwLock<T> | T |
std::time::Duration | { secs: number, nanos: number }, as serde writes it |
The Rust client uses the same Rust types. The Python client uses the matching
built-in types (int, float, str, list, dict, tuple, None),
Path for paths and timedelta for Duration.
A JavaScript number holds integers exactly only up to 253. A
u64 or i64 field whose values can go beyond that loses precision in a
TypeScript client. Send such values as strings: serialize the field as a
string and describe it as one with a type override.
Library types
Enable a feature of the reflectapi crate to use the types of another crate:
| Feature | Types | TypeScript |
|---|---|---|
chrono | DateTime<Utc>, DateTime<Local>, DateTime<FixedOffset>, NaiveDateTime, NaiveDate, NaiveTime | string |
chrono-tz | chrono_tz::Tz | string |
uuid | uuid::Uuid | string |
url | url::Url | string |
rust_decimal | rust_decimal::Decimal | string |
json | serde_json::Value; serde_json::Map as a map | any |
indexmap | IndexMap<K, V>, IndexSet<T>, as maps and sets | Record<K, V>, Array<T> |
cargo add reflectapi --features builder,chrono,uuid
The Rust client uses the same types, so a crate that includes it needs the
same libraries. The Python client uses datetime and date for chrono's
dates and UUID for uuid::Uuid.
Enums
Serde's enum representations are reflected, and each client's type matches the JSON. For this enum:
enum Shape { Circle { radius: f64 }, Empty, } use serde_json::to_string as json; #[derive(serde::Serialize)] enum External { Circle { radius: f64 }, Empty } #[derive(serde::Serialize)] #[serde(tag = "type")] enum Internal { Circle { radius: f64 }, Empty } #[derive(serde::Serialize)] #[serde(tag = "t", content = "c")] enum Adjacent { Circle { radius: f64 }, Empty } #[derive(serde::Serialize)] #[serde(untagged)] enum Untagged { Circle { radius: f64 }, Empty } fn main() { let _ = (Shape::Circle { radius: 1.0 }, Shape::Empty); assert_eq!(json(&External::Circle { radius: 1.0 }).unwrap(), r#"{"Circle":{"radius":1.0}}"#); assert_eq!(json(&External::Empty).unwrap(), r#""Empty""#); assert_eq!(json(&Internal::Circle { radius: 1.0 }).unwrap(), r#"{"type":"Circle","radius":1.0}"#); assert_eq!(json(&Internal::Empty).unwrap(), r#"{"type":"Empty"}"#); assert_eq!(json(&Adjacent::Circle { radius: 1.0 }).unwrap(), r#"{"t":"Circle","c":{"radius":1.0}}"#); assert_eq!(json(&Adjacent::Empty).unwrap(), r#"{"t":"Empty"}"#); assert_eq!(json(&Untagged::Circle { radius: 1.0 }).unwrap(), r#"{"radius":1.0}"#); assert_eq!(json(&Untagged::Empty).unwrap(), "null"); }
| Serde attribute | JSON | TypeScript |
|---|---|---|
| none (externally tagged) | {"Circle":{"radius":1.0}}, "Empty" | { Circle: { radius: number } } | "Empty" |
#[serde(tag = "type")] | {"type":"Circle","radius":1.0}, {"type":"Empty"} | { type: "Circle", radius: number } | { type: "Empty" } |
#[serde(tag = "t", content = "c")] | {"t":"Circle","c":{"radius":1.0}}, {"t":"Empty"} | { t: "Circle", c: { radius: number } } | { t: "Empty" } |
#[serde(untagged)] | {"radius":1.0}, null | { radius: number } | null |
The Rust client's enum has the same serde attributes. Python gets a model per variant and a union of them.
rename,rename_alland the other serde attributes on variants and fields are reflected too.- An enum whose responses may gain variants can be marked
#[reflectapi(open)], so that clients keep values with unfamiliar tags; see Enum evolution. - A unit enum that serde writes as numbers, for example with the
serde_reprcrate, needs#[reflectapi(discriminant)], so that clients use its discriminants (1 | 2in TypeScript) instead of its variant names.
Newtypes
A tuple struct with one field, struct UserId(u64), is written by serde as
its field, and so is a struct marked #[serde(transparent)]. The clients
alias it: type UserId = number in TypeScript and pub type UserId = u64 in
Rust; Python uses int in its place. The server keeps the distinct type; the
clients see the inner one.
Inline newtypes removes the alias names from
the clients too.
One type, two shapes
A type is reflected once as input and once as output, and the two can differ:
- a field can be optional in a request (
#[serde(default)]) but always present in a response; #[serde(skip_deserializing)]or#[reflectapi(input_skip)]leaves a field out of the input, and#[serde(skip_serializing)]or#[reflectapi(output_skip)]out of the output;#[reflectapi(input_type = "...")]and#[reflectapi(output_type = "...")]describe a field as a different type in each direction.
use serde::{Deserialize, Serialize}; #[derive(Serialize, Deserialize, reflectapi::Input, reflectapi::Output)] struct User { /// Set by the server. #[serde(skip_deserializing)] id: u64, name: String, } async fn users_create(_: (), user: User, _: reflectapi::Empty) -> User { User { id: 1, ..user } } fn main() -> Result<(), reflectapi::BuildErrors> { let (schema, _) = reflectapi::Builder::new() .route(users_create, |b| b.name("users.create")) .build()?; let fields = |types: &reflectapi::Typespace| { let user = types.types().find(|t| t.name().ends_with("::User")).unwrap(); user.as_struct().unwrap().fields().map(|f| f.name().to_owned()).collect::<Vec<_>>() }; assert_eq!(fields(schema.input_types()), ["name"]); assert_eq!(fields(schema.output_types()), ["id", "name"]); Ok(()) }
When the two shapes differ, the clients have two types, in input and
output namespaces: User becomes input.User, which the client sends,
and output.User, which it receives. A type whose shapes are the same stays
one type. Missing fields and null
has the rules for which fields are required in each direction.
Option and reflectapi::Option
std::option::Option<T> has two states, a value or null. In a request, a
missing field also reads as None, so the server can't tell "not sent" from
null. For a partial update, where leaving a field out means "keep it" and
null means "clear it", use
reflectapi::Option<T>,
which has three: Undefined, None and Some(T).
#![allow(unused)] fn main() { #[derive(serde::Serialize, serde::Deserialize, reflectapi::Input)] struct PetPatch { #[serde(default, skip_serializing_if = "reflectapi::Option::is_undefined")] age: reflectapi::Option<u8>, } let patch: PetPatch = serde_json::from_str("{}").unwrap(); assert!(patch.age.is_undefined()); let patch: PetPatch = serde_json::from_str(r#"{"age":null}"#).unwrap(); assert!(patch.age.is_none()); let patch: PetPatch = serde_json::from_str(r#"{"age":3}"#).unwrap(); assert_eq!(patch.age, reflectapi::Option::Some(3)); let undefined = PetPatch { age: reflectapi::Option::Undefined }; assert_eq!(serde_json::to_string(&undefined).unwrap(), "{}"); }
Reading needs #[serde(default)]: without it a missing field reads as
None. Writing needs skip_serializing_if: without it Undefined is written
as null. A request type the server only reads needs just
#[serde(default)]; this example, read and written, needs both. The clients keep the three states: the field is
age?: number | null | undefined in TypeScript, a reflectapi::Option<u8> in
Rust, and a Python model sends only the fields that were set. See
Missing fields and explicit null.
Empty and Infallible
reflectapi::Empty
is a struct with no fields, {} on the wire. Use it for a route with no
input, no output or no request headers. A request with an empty body is read
as {}, so an Empty input accepts it. () is null on the wire instead.
reflectapi::Infallible
is the error type of a route that can't fail. See
Errors.
#![allow(unused)] fn main() { assert_eq!(serde_json::to_string(&reflectapi::Empty {}).unwrap(), "{}"); assert_eq!(serde_json::to_string(&()).unwrap(), "null"); }
Types reflectapi doesn't know
A type that implements neither trait, such as std::net::IpAddr, can't be
used as it is. Tell reflectapi which known type has the same JSON.
For a field, override its type. Serde writes an IpAddr as a string:
#[derive(serde::Serialize, reflectapi::Output)] struct Server { #[reflectapi(type = "String")] address: std::net::IpAddr, #[reflectapi(type = "Vec::<String>")] fallbacks: Vec<std::net::IpAddr>, } fn main() { let _ = Server { address: [127, 0, 0, 1].into(), fallbacks: vec![] }; }
typesets both directions;input_typeandoutput_typeset one.- The string is a Rust type path. A generic type needs the turbofish:
"Vec::<String>", not"Vec<String>". - reflectapi doesn't check that serde writes what the override says. If they differ, the clients are wrong.
For a type of your own whose serde implementation is written by hand, put the
override on the type: it is reflected as the given type, under its own name.
Serde's #[serde(into = "...")], from and try_from are followed the same
way, with no override needed:
use serde::{Deserialize, Serialize}; /// A version, written as "1.2". #[derive(Clone, Serialize, Deserialize, reflectapi::Input, reflectapi::Output)] #[serde(into = "String", try_from = "String")] struct Version { major: u32, minor: u32, } impl From<Version> for String { fn from(v: Version) -> String { format!("{}.{}", v.major, v.minor) } } impl TryFrom<String> for Version { type Error = String; fn try_from(s: String) -> Result<Self, String> { let (major, minor) = s.split_once('.').ok_or("expected major.minor")?; let number = |s: &str| s.parse().map_err(|_| format!("not a number: {s}")); Ok(Version { major: number(major)?, minor: number(minor)? }) } } async fn version(_: (), v: Version, _: reflectapi::Empty) -> Version { v } fn main() -> Result<(), reflectapi::BuildErrors> { let (schema, _) = reflectapi::Builder::new() .route(version, |b| b.name("version")) .build()?; let version = schema .output_types() .types() .find(|t| t.name().ends_with("::Version")) .unwrap(); let field = version.as_struct().unwrap().fields().next().unwrap(); assert_eq!(field.type_ref().name(), "std::string::String"); Ok(()) }
The TypeScript client gets type Version = string. With a hand-written
Serialize, #[reflectapi(type = "String")] on the struct does the same.
Input and Output can also be implemented by hand. The simplest
implementation returns another type's reflection:
#![allow(unused)] fn main() { /// A temperature, written as a number. struct Celsius(f64); impl serde::Serialize for Celsius { fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> { self.0.serialize(serializer) } } impl reflectapi::Output for Celsius { fn reflectapi_output_type(schema: &mut reflectapi::Typespace) -> reflectapi::TypeReference { f64::reflectapi_output_type(schema) } } }
Unlike an override, this gives the type no name of its own: clients see an
f64. The orphan rule applies: a trait from reflectapi can be implemented
only for a type of your own crate, so use an override for a field of a type
from another crate.