Maintaining API Compatibility During Migration

20 min read

When you replace a Node.js endpoint with a Rust one, the endpoint’s contract must not change. Existing mobile apps, browser bundles, and downstream services keep talking to the same URL and expect the same bytes back: the same JSON keys, the same status codes, the same headers. This page is about making the Rust response indistinguishable from the Node response it replaces.

Quick Overview

A migration is safe only if clients cannot tell the difference. That means three things must match byte-for-byte (or header-for-header):

JSON shape: field names, casing, nesting, null-vs-omitted, number formats, date strings.
Status codes: 200 vs 201 vs 204, and the exact error codes (400 vs 404 vs 422 vs 500).
Headers: Content-Type, caching, Location, custom X-* headers, and their exact values.

The good news: Rust’s serde gives you precise, declarative control over the wire format, and axum lets you set status and headers explicitly. The discipline that makes this work is golden-fixture testing — capture real responses from the Node service, then assert the Rust service reproduces them exactly.

Note: This page assumes you have already chosen what to port (see incremental.md) and how a single endpoint moves from Express to Axum (see node-to-rust.md). Here we focus narrowly on keeping the wire contract identical.

TypeScript/JavaScript Example

Here is a representative Express handler. Notice every detail that a client might depend on — the casing of fullName, the omitted avatarUrl, the X-Request-Id header, the cache policy, and the shape of the error envelope.

1
// src/routes/users.ts (Express + TypeScript, Node v22)
2
import { Router, Request, Response } from "express";
3

4
const router = Router();
5

6
interface UserDto {
7
  id: number;
8
  fullName: string;
9
  email: string;
10
  avatarUrl?: string; // omitted from JSON when undefined
11
  isActive: boolean;
12
}
13

14
router.get("/users/:id", (req: Request, res: Response) => {
15
  const id = Number(req.params.id);
16
  const user = findUser(id); // returns UserDto | null
17

18
  if (user === null) {
19
    // The error envelope every client already parses.
20
    return res.status(404).json({
21
      error: { code: "USER_NOT_FOUND", message: "User not found" },
22
    });
23
  }
24

25
  res
26
    .status(200)
27
    .set("X-Request-Id", req.header("X-Request-Id") ?? "req-abc")
28
    .set("Cache-Control", "private, max-age=30")
29
    .json(user);
30
});
31

32
function findUser(id: number): UserDto | null {
33
  if (id === 0) return null;
34
  return { id, fullName: "Ada Lovelace", email: "ada@example.com", isActive: true };
35
}
36

37
export default router;

A success returns:

1
{ "id": 42, "fullName": "Ada Lovelace", "email": "ada@example.com", "isActive": true }

Note that avatarUrl is absent, not null. In JavaScript, JSON.stringify drops keys whose value is undefined. A naive Rust port that emits "avatarUrl": null would be a contract change.

Rust Equivalent

The same handler in Axum. The serde attributes encode the wire contract directly on the type, so the format is enforced by the compiler and visible at a glance.

1
use axum::{
2
    Json, Router,
3
    extract::Path,
4
    http::{HeaderName, HeaderValue, StatusCode, header},
5
    response::{IntoResponse, Response},
6
    routing::get,
7
};
8
use serde::Serialize;
9
use serde_json::json;
10

11
#[derive(Serialize)]
12
#[serde(rename_all = "camelCase")] // full_name -> "fullName", is_active -> "isActive"
13
struct UserDto {
14
    id: u64,
15
    full_name: String,
16
    email: String,
17
    #[serde(skip_serializing_if = "Option::is_none")] // omit when None, like JS `undefined`
18
    avatar_url: Option<String>,
19
    is_active: bool,
20
}
21

22
async fn get_user(Path(id): Path<u64>) -> Response {
23
    let user = find_user(id);
24

25
    let Some(user) = user else {
26
        // Exact same error envelope the Node service produced.
27
        return (
28
            StatusCode::NOT_FOUND,
29
            Json(json!({ "error": { "code": "USER_NOT_FOUND", "message": "User not found" } })),
30
        )
31
            .into_response();
32
    };
33

34
    (
35
        StatusCode::OK,
36
        [
37
            (HeaderName::from_static("x-request-id"), HeaderValue::from_static("req-abc")),
38
            (header::CACHE_CONTROL, HeaderValue::from_static("private, max-age=30")),
39
        ],
40
        Json(user),
41
    )
42
        .into_response()
43
}
44

45
fn find_user(id: u64) -> Option<UserDto> {
46
    if id == 0 {
47
        return None;
48
    }
49
    Some(UserDto {
50
        id,
51
        full_name: "Ada Lovelace".to_string(),
52
        email: "ada@example.com".to_string(),
53
        avatar_url: None,
54
        is_active: true,
55
    })
56
}
57

58
pub fn router() -> Router {
59
    // Axum 0.8 uses `{id}` for path params, not `:id`.
60
    Router::new().route("/users/{id}", get(get_user))
61
}

Serializing a UserDto { id: 42, .., avatar_url: None, .. } produces exactly:

1
{
2
  "id": 42,
3
  "fullName": "Ada Lovelace",
4
  "email": "ada@example.com",
5
  "isActive": true
6
}

The avatarUrl key is absent — matching the Express output byte-for-byte. This is real cargo run output from a probe project using serde 1.0, serde_json 1.0, and axum 0.8.

Note: Axum 0.8 changed the path-parameter syntax from :id (Axum 0.7) to {id}. If you copy an older tutorial you will hit a routing error. The current stable toolchain is Rust 1.96.0 on the 2024 edition; cargo new selects it automatically.

Detailed Explanation

Field casing: `rename_all`

serde serializes Rust field names verbatim by default, so a full_name field becomes "full_name" in JSON — snake_case, which would break a JS client expecting fullName. The container attribute #[serde(rename_all = "camelCase")] rewrites every field’s key. Without it:

1
use serde::Serialize;
2

3
#[derive(Serialize)]
4
struct AccountSnakeDefault {
5
    user_id: u64,
6
    is_active: bool,
7
}
8

9
fn main() {
10
    let a = AccountSnakeDefault { user_id: 7, is_active: true };
11
    println!("{}", serde_json::to_string(&a).unwrap());
12
}

Real output:

1
{"user_id":7,"is_active":true}

That user_id/is_active shape silently breaks any client reading userId/isActive. rename_all is the single most common attribute you will reach for during a Node migration, because Node codebases almost always use camelCase JSON.

`null` versus omitted

JavaScript and Rust disagree about absent values, and the difference is observable on the wire:

JS JSON.stringify({ a: undefined }) → {} (key dropped).
JS JSON.stringify({ a: null }) → {"a":null} (key present, value null).
Rust Option<T> serializes None as null by default.

So a plain avatar_url: Option<String> would emit "avatarUrl": null — different from the Express undefined behavior. The fix is #[serde(skip_serializing_if = "Option::is_none")], which omits the key entirely when the value is None. Choose deliberately per field: if the Node service emitted null, keep the field and do not add the skip attribute; if it omitted the key, add the skip attribute. They are not interchangeable.

Numbers: the big-integer trap

JavaScript’s number is always an IEEE-754 double (f64). Any integer above 2^53 cannot be represented exactly, and JSON.parse rounds it. This is a real loss, not theoretical:

1
raw string : 9007199254740993
2
after parse: 9007199254740992
3
round-trip equal to original string: false

(Real Node v22 output — 9007199254740993 becomes 9007199254740992 after JSON.parse.)

If your Node service already sends large IDs as JSON strings to dodge this, your Rust service must do the same. An i64 serializes as a JSON number by default, so you encode it as a string explicitly:

1
use serde::Serialize;
2

3
#[derive(Serialize)]
4
#[serde(rename_all = "camelCase")]
5
struct Account {
6
    // Serialize the 64-bit id as a JSON string so JS clients never lose precision.
7
    #[serde(serialize_with = "as_string")]
8
    account_id: i64,
9
    balance_cents: i64,
10
}
11

12
fn as_string<S>(value: &i64, s: S) -> Result<S::Ok, S::Error>
13
where
14
    S: serde::Serializer,
15
{
16
    s.serialize_str(&value.to_string())
17
}
18

19
fn main() {
20
    let acct = Account { account_id: 9_007_199_254_740_993, balance_cents: 4999 };
21
    println!("{}", serde_json::to_string(&acct).unwrap());
22
}

Real output:

1
{"accountId":"9007199254740993","balanceCents":4999}

The id is a quoted string; the balanceCents, which stays comfortably within the safe range, remains a number — matching whatever the Node service did field by field.

Dates and times

Node usually serializes a Date with toISOString(), producing RFC 3339 strings like "2026-06-02T10:00:00.000Z". With chrono (add chrono with the serde feature), a DateTime<Utc> serializes to RFC 3339 automatically:

1
use chrono::{DateTime, Utc};
2
use serde::Serialize;
3

4
#[derive(Serialize)]
5
#[serde(rename_all = "camelCase")]
6
struct Event {
7
    created_at: DateTime<Utc>,
8
}
9

10
fn main() {
11
    let event = Event { created_at: "2026-06-02T10:00:00Z".parse().unwrap() };
12
    println!("{}", serde_json::to_string(&event).unwrap());
13
}

Real output:

1
{"createdAt":"2026-06-02T10:00:00Z"}

Warning: Watch the fractional-seconds detail. Node’s toISOString() always includes milliseconds (.000), while chrono’s default RFC 3339 output omits them when they are zero. If a client does string comparison or strict schema validation, normalize the format on one side. You can force a specific layout with created_at.to_rfc3339_opts(SecondsFormat::Millis, true) inside a custom serialize_with.

Status codes and headers in Axum

In Express you chain res.status(200).set(...).json(...). In Axum you return a tuple that Axum turns into a response via the IntoResponse trait. The tuple convention is (StatusCode, [headers], Json(body)), and order matters: status first, headers next, body last. Each element must itself implement IntoResponse or be a recognized header collection.

Driving the handler in-process (via tower’s oneshot) gives reproducible, real output:

1
GET /users/42 -> 200 OK
2
x-request-id: "req-abc"
3
cache-control: "private, max-age=30"
4
content-type: "application/json"
5
body: {"id":42,"fullName":"Ada Lovelace","email":"ada@example.com","isActive":true}
6
GET /users/0 -> 404 Not Found
7
body: {"error":{"code":"USER_NOT_FOUND","message":"User not found"}}

Two things to notice. First, Json(...) sets Content-Type: application/json for you, exactly as Express’s res.json() does — you do not (and should not) set it manually. Second, the 404 branch returns the identical error envelope. The status line and the body are both part of the contract; matching one without the other is still a breaking change.

Key Differences

Concern	Express / Node	Axum / Rust
Field casing	Whatever the object literal uses (usually camelCase)	snake_case by default; use `#[serde(rename_all = "camelCase")]`
Absent value	`undefined` → key dropped	`None` → `null` by default; add `skip_serializing_if` to drop
Explicit null	`null` → `{"k":null}`	`None` → `{"k":null}` (matches without extra attributes)
Large integers	All numbers are `f64`; precision lost > 2^53	`i64`/`u64` exact; serialize as string to match a string-id contract
Dates	`Date.toISOString()` (always `.000` ms)	`chrono` RFC 3339 (omits zero ms by default)
Status code	`res.status(n)`	First element of the returned tuple, e.g. `StatusCode::CREATED`
Content-Type	`res.json()` sets `application/json`	`Json(...)` sets `application/json`
Custom headers	`res.set("X-Foo", v)`	`[(HeaderName::from_static("x-foo"), HeaderValue::from_static(v))]`
Header name case	Sent as written; HTTP/2 lowercases	Always stored lowercase internally
Contract enforcement	Runtime only; types erased	Declared on the type; checked at compile time

The deepest difference is where the contract lives. In TypeScript the interface UserDto is erased at runtime — nothing stops you returning a differently-shaped object. In Rust the serde attributes are the serialization, so the wire format is welded to the type and verified when you compile. That is exactly the property you want during a migration: the format cannot drift by accident.

Tip: Header names in HTTP are case-insensitive, and Axum normalizes them to lowercase. If you assert against "X-Request-Id" with exact casing in a test, look it up as x-request-id. Clients should already treat header names case-insensitively, but a strict test harness might not.

Common Pitfalls

Forgetting `rename_all`

The most frequent break. You port the struct, forget the container attribute, and every key ships as snake_case. The Rust compiles cleanly and the tests you forgot to write pass — but the mobile app shows blank fields. Always diff the first real response against a captured Node payload.

Returning a tuple where a `Response` is expected

If a function’s return type is Response but you return the convenience tuple in some branches, the types do not line up and Rust stops you:

1
use axum::{Json, http::StatusCode, response::Response};
2
use serde_json::json;
3

4
// does not compile (error[E0308]: mismatched types)
5
async fn handler(found: bool) -> Response {
6
    if found {
7
        (StatusCode::OK, Json(json!({ "ok": true })))
8
    } else {
9
        (StatusCode::NOT_FOUND, Json(json!({ "error": "missing" })))
10
    }
11
}
12

13
fn main() {}

The real compiler error:

1
error[E0308]: mismatched types
2
 --> src/main.rs:9:9
3
  |
4
7 | async fn handler(found: bool) -> Response {
5
  |                                  -------- expected `Response<Body>` because of return type
6
8 |     if found {
7
9 |         (StatusCode::OK, Json(json!({ "ok": true })))
8
  |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ expected `Response<Body>`, found `(StatusCode, Json<Value>)`
9
  |
10
  = note: expected struct `Response<Body>`
11
              found tuple `(StatusCode, Json<Value>)`

The fix is to call .into_response() on each branch (as the Rust Equivalent above does), or change the return type to impl IntoResponse when every branch has the same tuple type. This compile error is a feature: it forces every branch to agree on the response type.

`null` versus omitted, again

It is worth repeating because it is silent. Default Option<T> emits null; the Node code may have emitted nothing. The mismatch will not error — clients that do if (user.avatarUrl) keep working, but clients that do "avatarUrl" in user or schema-validate with additionalProperties: false will diverge. Decide per field and write a test that pins it.

Trailing-slash and path-param mismatches

Express matches /users/42 and /users/42/ somewhat loosely depending on configuration. Axum is stricter and uses {id}, not :id. If clients call a trailing-slash variant, add explicit routes or a normalization layer rather than assuming parity.

Structured deserialize errors leak as 400, not 422

When a request body fails to parse, Axum’s Json extractor rejects it with 400 Bad Request and a plain-text message — not your JSON error envelope, and not the 422 your Node validation layer may have used. The underlying serde error is precise and useful (missing field `fullName` at line 1 column 27), but you must catch it and remap it to keep the contract. See the Best Practices and the Real-World example below.

Best Practices

Capture golden fixtures from the Node service

Before you delete a single line of Node, record real responses — status, headers, body — for representative requests. A few curl -i captures committed as files become your contract. Then assert the Rust service reproduces them. Compare bodies as parsed serde_json::Value, not as strings, so key ordering and whitespace do not cause false failures while still catching every shape difference:

1
use serde_json::json;
2

3
fn main() {
4
    // `actual` would come from your handler's response body in a real test.
5
    let actual: serde_json::Value =
6
        serde_json::from_str(r#"{"fullName":"Ada","id":42}"#).unwrap();
7

8
    // Field order differs, but the documents are equal.
9
    let golden = json!({ "id": 42, "fullName": "Ada" });
10

11
    assert_eq!(actual, golden);
12
    println!("contract holds");
13
}

Real output: contract holds. Parsed-value comparison ignores key order (JSON objects are unordered) but catches missing keys, extra keys, wrong casing, null-vs-omitted, and type changes.

Centralize the error envelope with one `IntoResponse` type

Do not hand-write the error JSON at every call site — you will eventually get one wrong. Define a single error enum whose IntoResponse impl maps each variant to a status code and the shared envelope. Every handler returns it, so the format cannot drift:

1
use axum::{Json, http::StatusCode, response::{IntoResponse, Response}};
2
use serde_json::json;
3

4
enum ApiError {
5
    NotFound(String),
6
    Validation(String),
7
    Internal,
8
}
9

10
impl IntoResponse for ApiError {
11
    fn into_response(self) -> Response {
12
        let (status, code, message) = match self {
13
            ApiError::NotFound(what) => {
14
                (StatusCode::NOT_FOUND, "NOT_FOUND", format!("{what} not found"))
15
            }
16
            ApiError::Validation(msg) => {
17
                (StatusCode::UNPROCESSABLE_ENTITY, "VALIDATION_ERROR", msg)
18
            }
19
            ApiError::Internal => (
20
                StatusCode::INTERNAL_SERVER_ERROR,
21
                "INTERNAL",
22
                "Internal server error".to_string(),
23
            ),
24
        };
25
        (status, Json(json!({ "error": { "code": code, "message": message } }))).into_response()
26
    }
27
}
28

29
fn main() {
30
    for err in [
31
        ApiError::NotFound("User".into()),
32
        ApiError::Validation("email is required".into()),
33
        ApiError::Internal,
34
    ] {
35
        println!("status = {}", err.into_response().status());
36
    }
37
}

Real output:

1
status = 404 Not Found
2
status = 422 Unprocessable Entity
3
status = 500 Internal Server Error

This is the single biggest lever for error-contract parity. Map your Node error codes onto variants once, and every endpoint inherits the right status and the right body.

Stay backward-compatible on input with `#[serde(default)]`

When the Rust version adds an optional request field, old clients omit it. Mark it #[serde(default)] so their requests still parse:

1
use serde::Deserialize;
2

3
#[derive(Deserialize, Debug)]
4
#[serde(rename_all = "camelCase")]
5
struct CreateUser {
6
    full_name: String,
7
    email: String,
8
    #[serde(default)] // old clients omit `marketingOptIn`; defaults to false
9
    marketing_opt_in: bool,
10
}
11

12
fn main() {
13
    let body = r#"{"fullName":"Ada","email":"ada@example.com"}"#;
14
    let parsed: CreateUser = serde_json::from_str(body).unwrap();
15
    println!("{parsed:?}");
16
}

Real output:

1
CreateUser { full_name: "Ada", email: "ada@example.com", marketing_opt_in: false }

Be deliberate about unknown input fields

By default serde ignores unknown fields when deserializing, which is forgiving and usually what you want during a migration (a client sending an extra key keeps working). If you instead want to reject unexpected input, add #[serde(deny_unknown_fields)] — but only if your Node service also rejected them, or you will introduce a new failure mode that did not exist before.

Match the format, not just the values

Content-Type charset (application/json vs application/json; charset=utf-8), header ordering, and cache directives are all part of what some clients and CDNs key on. When in doubt, capture the Node response with curl -i and diff the full header block.

Real-World Example

A production-flavored order endpoint that ties everything together: camelCase keys, a big id serialized as a string, RFC 3339 dates, an omitted optional field, a custom cache header, a centralized error type, and a contract assertion against a golden fixture captured from the Node service it replaces.

1
use axum::{
2
    Json, Router,
3
    extract::Path,
4
    http::{HeaderValue, StatusCode, header},
5
    response::{IntoResponse, Response},
6
    routing::get,
7
};
8
use chrono::{DateTime, Utc};
9
use serde::Serialize;
10
use serde_json::json;
11

12
#[derive(Serialize)]
13
#[serde(rename_all = "camelCase")]
14
struct OrderDto {
15
    id: String,
16
    #[serde(serialize_with = "as_string")] // 64-bit id as JSON string for JS safety
17
    account_id: i64,
18
    amount_cents: i64,
19
    currency: String,
20
    status: String,
21
    created_at: DateTime<Utc>,
22
    #[serde(skip_serializing_if = "Option::is_none")] // omit, do not emit null
23
    coupon: Option<String>,
24
}
25

26
fn as_string<S: serde::Serializer>(v: &i64, s: S) -> Result<S::Ok, S::Error> {
27
    s.serialize_str(&v.to_string())
28
}
29

30
enum ApiError {
31
    NotFound,
32
}
33

34
impl IntoResponse for ApiError {
35
    fn into_response(self) -> Response {
36
        let (status, code, message) = match self {
37
            ApiError::NotFound => (StatusCode::NOT_FOUND, "ORDER_NOT_FOUND", "Order not found"),
38
        };
39
        (status, Json(json!({ "error": { "code": code, "message": message } }))).into_response()
40
    }
41
}
42

43
async fn get_order(Path(id): Path<String>) -> Result<Response, ApiError> {
44
    if id != "ord_123" {
45
        return Err(ApiError::NotFound);
46
    }
47
    let order = OrderDto {
48
        id,
49
        account_id: 9_007_199_254_740_993,
50
        amount_cents: 4999,
51
        currency: "USD".to_string(),
52
        status: "paid".to_string(),
53
        created_at: "2026-06-02T10:00:00Z".parse().unwrap(),
54
        coupon: None,
55
    };
56
    Ok((
57
        StatusCode::OK,
58
        [(header::CACHE_CONTROL, HeaderValue::from_static("private, max-age=30"))],
59
        Json(order),
60
    )
61
        .into_response())
62
}
63

64
pub fn router() -> Router {
65
    Router::new().route("/orders/{id}", get(get_order))
66
}
67

68
#[tokio::main]
69
async fn main() {
70
    use tower::ServiceExt; // for `oneshot`
71

72
    let resp = router()
73
        .oneshot(
74
            axum::http::Request::builder()
75
                .uri("/orders/ord_123")
76
                .body(axum::body::Body::empty())
77
                .unwrap(),
78
        )
79
        .await
80
        .unwrap();
81

82
    let status = resp.status();
83
    let cache = resp.headers().get("cache-control").cloned();
84
    let body = axum::body::to_bytes(resp.into_body(), usize::MAX).await.unwrap();
85
    let actual: serde_json::Value = serde_json::from_slice(&body).unwrap();
86

87
    // Golden contract fixture captured from the Node service being replaced.
88
    let golden = json!({
89
        "id": "ord_123",
90
        "accountId": "9007199254740993",
91
        "amountCents": 4999,
92
        "currency": "USD",
93
        "status": "paid",
94
        "createdAt": "2026-06-02T10:00:00Z"
95
    });
96

97
    println!("status: {status}");
98
    println!("cache-control: {cache:?}");
99
    println!("body matches golden fixture: {}", actual == golden);
100
}

Cargo.toml dependencies (resolved with cargo add):

1
[dependencies]
2
axum = "0.8"
3
tokio = { version = "1", features = ["full"] }
4
serde = { version = "1", features = ["derive"] }
5
serde_json = "1"
6
chrono = { version = "0.4", features = ["serde"] }
7

8
[dev-dependencies]
9
tower = { version = "0.5", features = ["util"] } # oneshot for in-process tests

Real output:

1
status: 200 OK
2
cache-control: Some("private, max-age=30")
3
body matches golden fixture: true

The oneshot call drives the router in-process, so this same pattern becomes a #[tokio::test]: build a request, call oneshot, and assert the status, headers, and parsed body against fixtures. Run it against every endpoint you port and the contract is guarded by CI. For more on testing Axum services, see 16-web-apis/README.md and 08-error-handling/README.md.

Exercises

Exercise 1: Match an exact JSON shape

Difficulty: Beginner

Objective: Produce JSON that is byte-for-byte identical to a captured Node payload.

Instructions: A Node endpoint returns this body for a product:

1
{ "productId": "p_99", "displayName": "Keyboard", "priceCents": 7999, "inStock": true }

Define a Rust struct with #[derive(Serialize)] and the right serde attributes so that serializing it produces exactly those keys (camelCase) in a struct whose Rust fields are snake_case. Print the result and confirm it matches.

Solution

1
use serde::Serialize;
2

3
#[derive(Serialize)]
4
#[serde(rename_all = "camelCase")]
5
struct Product {
6
    product_id: String,
7
    display_name: String,
8
    price_cents: i64,
9
    in_stock: bool,
10
}
11

12
fn main() {
13
    let product = Product {
14
        product_id: "p_99".to_string(),
15
        display_name: "Keyboard".to_string(),
16
        price_cents: 7999,
17
        in_stock: true,
18
    };
19

20
    let actual: serde_json::Value =
21
        serde_json::from_str(&serde_json::to_string(&product).unwrap()).unwrap();
22

23
    let golden: serde_json::Value = serde_json::from_str(
24
        r#"{ "productId": "p_99", "displayName": "Keyboard", "priceCents": 7999, "inStock": true }"#,
25
    )
26
    .unwrap();
27

28
    println!("{}", serde_json::to_string(&product).unwrap());
29
    assert_eq!(actual, golden);
30
    println!("matches golden fixture");
31
}

Real output:

1
{"productId":"p_99","displayName":"Keyboard","priceCents":7999,"inStock":true}
2
matches golden fixture

#[serde(rename_all = "camelCase")] does all the work; comparing parsed Values makes the assertion order-insensitive.

Exercise 2: Reproduce a `201 Created` with a `Location` header

Difficulty: Intermediate

Objective: Match a Node create endpoint’s status code and headers, not just its body.

Instructions: A Node endpoint handles POST /articles. On success it does res.status(201).location('/articles/' + id).json(article). Write an Axum handler that accepts { "title": "...", "tags": [...] } (tags optional), returns 201 Created, sets a Location header pointing at the new resource, and returns the created article as camelCase JSON. Drive it with oneshot and print the status, the Location header, and the body.

Solution

1
use axum::{
2
    Json, Router,
3
    http::{HeaderValue, StatusCode, header},
4
    response::{IntoResponse, Response},
5
    routing::post,
6
};
7
use serde::{Deserialize, Serialize};
8

9
#[derive(Deserialize)]
10
#[serde(rename_all = "camelCase")]
11
struct NewArticle {
12
    title: String,
13
    #[serde(default)] // old clients may omit tags entirely
14
    tags: Vec<String>,
15
}
16

17
#[derive(Serialize)]
18
#[serde(rename_all = "camelCase")]
19
struct Article {
20
    id: u64,
21
    title: String,
22
    tags: Vec<String>,
23
}
24

25
async fn create_article(Json(body): Json<NewArticle>) -> Response {
26
    let id = 101; // a real handler would insert and get the generated id
27
    let article = Article { id, title: body.title, tags: body.tags };
28
    let location = format!("/articles/{id}");
29
    (
30
        StatusCode::CREATED,
31
        [(header::LOCATION, HeaderValue::from_str(&location).unwrap())],
32
        Json(article),
33
    )
34
        .into_response()
35
}
36

37
fn router() -> Router {
38
    Router::new().route("/articles", post(create_article))
39
}
40

41
#[tokio::main]
42
async fn main() {
43
    use tower::ServiceExt;
44
    let resp = router()
45
        .oneshot(
46
            axum::http::Request::builder()
47
                .method("POST")
48
                .uri("/articles")
49
                .header("content-type", "application/json")
50
                .body(axum::body::Body::from(r#"{"title":"Hello"}"#))
51
                .unwrap(),
52
        )
53
        .await
54
        .unwrap();
55

56
    println!("status: {}", resp.status());
57
    println!("location: {:?}", resp.headers().get("location").unwrap());
58
    let body = axum::body::to_bytes(resp.into_body(), usize::MAX).await.unwrap();
59
    println!("body: {}", String::from_utf8_lossy(&body));
60
}

Real output:

1
status: 201 Created
2
location: "/articles/101"
3
body: {"id":101,"title":"Hello","tags":[]}

#[serde(default)] on tags lets a request omit the field; the empty Vec serializes back as [], matching what the Node default would produce. HeaderValue::from_str is used (not from_static) because the value is built at runtime.

Exercise 3: Match a TypeScript discriminated union

Difficulty: Advanced

Objective: Reproduce a tagged-union JSON shape that a TypeScript client expects.

Instructions: A Node service returns a payment method as a discriminated union:

1
type PaymentMethod =
2
  | { type: "card"; last4: string }
3
  | { type: "paypal"; email: string };

Model this in Rust so that serializing it produces JSON with a "type" discriminator key, e.g. { "type": "card", "last4": "4242" } and { "type": "paypal", "email": "..." }. Serialize a list containing one of each variant and print the result.

Solution

1
use serde::Serialize;
2

3
// `tag = "type"` makes serde emit an internally-tagged enum,
4
// matching the TS discriminated union with a `type` discriminator.
5
#[derive(Serialize)]
6
#[serde(tag = "type", rename_all = "snake_case")]
7
enum PaymentMethod {
8
    Card { last4: String },
9
    Paypal { email: String },
10
}
11

12
fn main() {
13
    let methods = vec![
14
        PaymentMethod::Card { last4: "4242".to_string() },
15
        PaymentMethod::Paypal { email: "ada@example.com".to_string() },
16
    ];
17
    println!("{}", serde_json::to_string_pretty(&methods).unwrap());
18
}

Real output:

1
[
2
  {
3
    "type": "card",
4
    "last4": "4242"
5
  },
6
  {
7
    "type": "paypal",
8
    "email": "ada@example.com"
9
  }
10
]

#[serde(tag = "type")] selects the internally-tagged representation — the variant name becomes the value of the type key, and rename_all = "snake_case" lowercases Card/Paypal to card/paypal to match the TypeScript string literals. The same enum can #[derive(Deserialize)] too, so requests in this shape parse back into the right variant.

Maintaining API Compatibility During Migration

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Field casing: rename_all

null versus omitted

Numbers: the big-integer trap

Dates and times

Status codes and headers in Axum

Key Differences

Common Pitfalls

Forgetting rename_all

Returning a tuple where a Response is expected

null versus omitted, again

Trailing-slash and path-param mismatches

Structured deserialize errors leak as 400, not 422

Best Practices

Capture golden fixtures from the Node service

Centralize the error envelope with one IntoResponse type

Stay backward-compatible on input with #[serde(default)]

Be deliberate about unknown input fields

Match the format, not just the values

Real-World Example

Further Reading

Exercises

Exercise 1: Match an exact JSON shape

Exercise 2: Reproduce a 201 Created with a Location header

Exercise 3: Match a TypeScript discriminated union

Field casing: `rename_all`

`null` versus omitted

Forgetting `rename_all`

Returning a tuple where a `Response` is expected

`null` versus omitted, again

Centralize the error envelope with one `IntoResponse` type

Stay backward-compatible on input with `#[serde(default)]`

Exercise 2: Reproduce a `201 Created` with a `Location` header