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

Evolving an API

A generated client is compiled against one version of the schema, and keeps running after the server changes: in a browser tab left open, an app on a phone, or a service deployed on its own schedule. This page lists which server changes such clients survive, and how to make the others safely.

Two directions matter:

  • Old client, new server: the server is deployed first, and clients generated before the change keep calling it. This is the usual case.
  • New client, old server: a regenerated client reaches a server that doesn't have the change yet, during a rollout or a rollback.

What clients tolerate

Generated clients ignore response fields they don't know. Python models are generated with extra="ignore", the Rust client's serde types ignore unknown fields, and the TypeScript client doesn't check a response's fields at runtime. A server built with reflectapi ignores unknown request fields too, unless the type has #[serde(deny_unknown_fields)].

A missing field is another matter. A Python model rejects a response without a field it requires, and so does Rust for a field that isn't an Option. TypeScript checks a response only on routes that can return an open enum or a #[serde(other)] fallback; elsewhere the field is undefined where its type says it's present. The server answers a request missing a required field with 400.

Type names are not on the wire: the JSON holds field names, variant tags and values. Moving a type to another module or renaming it only changes the generated code. A route is called at {path}/{name}, so its name and its builder's path are on the wire.

Changes at a glance

ChangeOld client, new serverNew client, old server
Add a response fieldSafeBreaks where the new client requires the field
Add an optional request fieldSafeSafe, but the old server ignores the value
Add a required request fieldBreaks: 400Safe, but the old server ignores the value
Remove a response fieldBreaks where the old client requires the fieldSafe
Remove a request fieldSafe: the server ignores itBreaks if the old server requires it
Rename a field, keeping its serde nameSafeSafe
Add a response enum variantBreaks when sent, unless the enum is open or has a fallbackSafe
Add a request enum variantSafeBreaks when sent: 400
Add a routeSafe404 when called
Remove or rename a route, or change its path404 when calledSafe
Rename or move a typeSafeSafe

"Breaks" for a response means a Python client raises a validation error (for an error response, an ApplicationError whose typed_error is None), a Rust client returns a protocol error, and a TypeScript client usually hands the caller a value its types don't describe. Changing a field's type breaks whenever a value of one type doesn't decode as the other.

Adding fields

A new response field is safe for deployed clients. Deploy the server before clients that rely on it.

A new request field must be optional for the clients that don't send it: an Option<T>, which a missing key leaves None, or a field with #[serde(default)]. Generated clients then let callers leave it out, and a request from a client generated before the change still decodes:

use reflectapi::dispatch::{Dispatcher, Reply};

#[derive(serde::Deserialize, reflectapi::Input)]
struct CreatePetRequest {
    name: String,
    // Added after clients shipped.
    #[serde(default)]
    tags: Vec<String>,
    nickname: Option<String>,
}

async fn create(_: (), request: CreatePetRequest, _: reflectapi::Empty) -> String {
    request.name
}

#[tokio::main]
async fn main() {
let (schema, routers) = reflectapi::Builder::<()>::new()
    .route(create, |b| b.name("pets.create"))
    .build()
    .unwrap();

// Clients generated from the new schema may leave the new fields out...
let request = schema
    .input_types()
    .types()
    .find(|t| t.name().ends_with("CreatePetRequest"))
    .and_then(|t| t.as_struct())
    .unwrap();
let optional: Vec<&str> = request.fields().filter(|f| !f.required).map(|f| f.name()).collect();
assert_eq!(optional, ["tags", "nickname"]);

// ...and a request from a client generated before them still succeeds.
let reply = Dispatcher::new(routers)
    .dispatch(
        (),
        &http::Method::POST,
        "/pets.create",
        &http::HeaderMap::new(),
        r#"{"name":"Rex"}"#.into(),
    )
    .await;
assert!(matches!(reply, Some(Reply::Complete { status, .. }) if status == 200));
}

Without #[serde(default)], the same request gets 400 for the missing tags. See Missing fields and null for how defaults, Option and reflectapi::Option map to required and nullable fields in each direction.

Generated Rust types don't derive Default unless the type asks for it with #[reflectapi(derive(Default))], so Rust code that builds a request with a struct literal must add the new field after regenerating.

Removing and renaming fields

To rename a field in Rust without changing the wire, keep its old name with #[serde(rename = "...")]. Neither deployed nor regenerated clients notice: clients name a field after its serde name, and use the Rust identifier only when the serde name can't be one.

To remove a response field, deprecate it first:

#![allow(unused)]
fn main() {
#[derive(serde::Serialize, reflectapi::Output)]
struct Pet {
    name: String,
    #[deprecated(note = "Use `name`.")]
    #[reflectapi(sunset = "2027-01-01")]
    title: String,
}

#[allow(deprecated)]
async fn get(_: (), _: reflectapi::Empty, _: reflectapi::Empty) -> Pet {
    Pet { name: "Rex".into(), title: "Rex".into() }
}

let (schema, _) = reflectapi::Builder::<()>::new()
    .route(get, |b| b.name("pets.get"))
    .build()
    .unwrap();
let files = reflectapi::codegen::typescript::generate(schema, &Default::default()).unwrap();
assert!(files["generated.ts"].contains("title?: string"));
}

The server still sends title, but clients generated from now on treat it as optional: title?: string in TypeScript, an Option in Rust, and None when missing in Python. Once the clients generated before the deprecation are gone, removing the field breaks nothing. This applies to named fields of types used only in responses. A type also used in requests keeps the field required, and so does a type a client decodes by trying alternatives: an untagged enum, an enum with an untagged variant, or the type of a flattened Option field.

To remove a request field, first make it optional, so new clients can stop sending it, then remove it once the clients that require it are gone. The server ignores the field if an old client still sends it.

Deprecations covers declaring the release, the dates and the note, and what each client shows. A sunset date is an announcement: reflectapi doesn't know which clients are still deployed.

Adding enum variants

A client generated from a closed response enum can't decode a variant it doesn't know. Mark the enum #[reflectapi(open)], or give it a #[serde(other)] unit variant, before you need to add variants: clients generated after that accept unknown tags as an explicit unknown case or as the fallback. Clients generated earlier don't. See Enum evolution for the attribute and Handling unfamiliar enum variants for client code.

The server decodes a request enum with serde, so it rejects a variant it doesn't know with 400, unless the enum has a #[serde(other)] variant. Generated request enums stay closed, so a client sends only the variants it was generated with: a new request variant is safe once every server has it.

A route's error is a response type, so the same applies to a new error variant. See Errors for what a client does with an error it can't decode.

Adding, removing and renaming routes

A new route is safe for deployed clients. A removed or renamed route answers 404 to the clients that still call it, so deprecate it first and keep it until they are gone. To rename one, register the same handler under both names, with the old one deprecated; the demo does this for pets.delete:

#![allow(unused)]
fn main() {
async fn pets_remove(_: (), _: reflectapi::Empty, _: reflectapi::Empty) {}
let builder = reflectapi::Builder::<()>::new()
    .route(pets_remove, |b| b.name("pets.remove"))
    .route(pets_remove, |b| {
        b.name("pets.delete")
            .deprecation_note("Use pets.remove instead.")
            .sunset("2027-01-01")
    });
let (schema, _) = builder.build().unwrap();
assert_eq!(schema.functions().count(), 2);
}

Changing a builder's path or a route's name moves the route in the same way. See Organising a Larger API.

Keeping clients in sync

Generate the schema and the clients from the server's code, commit them, and have CI regenerate them and fail on a difference. Generate the schema and clients at build time shows a test that does it. Every API change then shows up in review as a diff of the committed schema and clients, next to the code that caused it. Use the table above to check that diff.

A TypeScript or Rust client compiled in the same repository fails to build when a change breaks the code that calls it. That catches breaks in the code you have, not in clients already deployed.