HTTP API: Explicit Contracts · 25 min · free lesson

Route Method and Path Together

Separate unknown routes from disallowed methods.

Core idea

Resolve the resource first, then the allowed HTTP method.

Diagram for Route Method and Path Together: a Rust code example flows to the lesson rule and the key observation.
The worked implementation exercises separate unknown routes from disallowed methods. Its tests demonstrate the stated finite contract.

Understand it

An HTTP method is part of the request contract. GET /tasks lists tasks; POST /tasks creates one. A known resource with a disallowed method is different from a path the application does not own. This lab returns 405 for unsupported methods on /tasks and 404 for unknown paths; GET /health returns 200, while other health methods return 405.

The request target can include a query string. Separate it before matching the path, but do not lowercase the path or decode arbitrary escapes without a policy: route names can be case sensitive. The lab implements literal paths only. A desktop Axum router handles the transport; the on-device adapter passes a bounded real HTTP request to Rust through stdin. It is an HTTP/1.x adapter with one response per connection, not an implementation of every HTTP version or chunked body mode.

The route project is Task Ledger: first keep a reproducible source history, then expose its data through a CLI and HTTP boundary, persist it in SQL, diagnose failures and prepare a release. This lesson owns one contract in that project. Run the worked example before changing the starter and explain which input makes the tempting shortcut fail.

Terminal practice: Run cargo serve --port 8080 --database tasks.db, then curl -i http://127.0.0.1:8080/tasks and curl -i -X DELETE http://127.0.0.1:8080/tasks. Stop with http stop.

The compiler lab is independent of the reading question. Edit solution.rs; the app supplies a separate caller with normal, empty and adversarial inputs. A successful unchanged demonstration does not prove your implementation. After the lab, apply the same contract to the route companion project. Its README separates the on-device adapter from the desktop Cargo/TCP profile.

Read the code

pub fn route(method: &str, target: &str) -> u16 {
    match target.split('?').next().unwrap_or("") {
        "/tasks" => match method {
            "GET" => 200,
            "POST" => 201,
            _ => 405,
        },
        "/health" => {
            if method == "GET" {
                200
            } else {
                405
            }
        }
        _ => 404,
    }
}

fn main() {
    assert_eq!(route("GET", "/tasks?limit=5"), 200, "case 1");
    assert_eq!(route("GET", "/missing"), 404, "case 2");
    assert_eq!(route("DELETE", "/tasks"), 405, "case 3");
    assert_eq!(route("POST", "/tasks"), 201, "case 4");
    assert_eq!(route("GET", "/Tasks"), 404, "case 5");
    assert_eq!(route("POST", "/health"), 405, "case 6");
    println!("worked example passed");
}

The worked implementation exercises separate unknown routes from disallowed methods. Its tests demonstrate the stated finite contract.

Practice starter

pub fn route(method: &str, target: &str) -> u16 {
    todo!("implement the contract")
}

Open local example in Playground ↗

Try it

Match literal /tasks and /health after removing the query string. GET tasks=200, POST tasks=201, GET health=200; other methods on those paths=405, unknown paths=404. Keep the public signature. Open the compiler lab and edit solution.rs; do not edit the private verification caller.

What success looks like: The separate caller accepts the changed solution and rejects unchanged TODO, a wrong implementation and a printed success message.

Check your understanding

What distinguishes 405 from 404 in this routing contract?

Reveal the answer
  1. Both statuses always mean the same thing
  2. An unknown path should return 200 with an empty body
  3. The resource exists but the method is disallowed

Matching only a method or only a path loses the distinction between unsupported operations and unknown resources.

Go deeper

Common misconception: Both statuses always mean the same thing

Resolve the resource first, then the allowed HTTP method.

  1. Identify the boundary: Separate unknown routes from disallowed methods. Write down its accepted inputs and observable output.
  2. Exercise the failure: Matching only a method or only a path loses the distinction between unsupported operations and unknown resources.
  3. Check the independent caller: Match literal /tasks and /health after removing the query string. GET tasks=200, POST tasks=201, GET health=200; other methods on those paths=405, unknown paths=404.

Transfer challenge: Apply this contract to Task Ledger, introduce the failure described in the lesson, and show the failing check before fixing it.

Connections

  • Separate Output from Failure: Return observable stdout, stderr and exit status
  • Validate Before Applying Effects: Check declared and actual request size