Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 38 ยท Getting Started

HTTP Basics for Axum Developers

Review the HTTP concepts every Axum handler uses: methods, status codes, headers, bodies and content types, with Rust types from the http crate and runnable models.

Every Axum handler is, at heart, a conversation in HTTP. A client sends a request made of a method, a path, headers and an optional body; your service sends back a status code, headers and an optional body. If you know these building blocks well, Axum's types will feel obvious, because they mirror HTTP almost one to one.

This lesson reviews what you need, and shows the matching Rust types from the http crate that Axum re-exports (axum::http). The examples at the end are runnable models that behave like the real types, so you can experiment with status codes and headers without a server.

Methods

The method says what the client wants to do with the resource at the path.

Method Typical meaning Safe? Idempotent? Has body?
GET Read a resource yes yes no
POST Create, or run an action no no yes
PUT Replace a resource completely no yes yes
PATCH Change part of a resource no no (usually) yes
DELETE Remove a resource no yes rarely
HEAD Like GET, headers only yes yes no
OPTIONS Ask what is allowed (CORS preflight) yes yes no

Safe means the request should not change server state; idempotent means doing it twice has the same effect as doing it once. These properties matter: browsers and proxies may retry or cache based on them.

In Axum, a method is axum::http::Method, and you attach handlers per method with helpers such as get, post, put, patch and delete. You will use them in routing basics.

Status codes

The status code is a three-digit number grouped by its first digit:

  • 1xx informational (rarely seen by handlers).
  • 2xx success: 200 OK, 201 Created, 202 Accepted, 204 No Content.
  • 3xx redirection: 301/308 permanent, 302/307 temporary, 304 Not Modified.
  • 4xx the client made a mistake: 400 Bad Request, 401 Unauthorized (really "unauthenticated"), 403 Forbidden, 404 Not Found, 405 Method Not Allowed, 409 Conflict, 415 Unsupported Media Type, 422 Unprocessable Content, 429 Too Many Requests.
  • 5xx the server failed: 500 Internal Server Error, 502, 503 Service Unavailable, 504 Gateway Timeout.

In Rust, axum::http::StatusCode has a constant for each: StatusCode::CREATED, StatusCode::NOT_FOUND, and so on. Prefer the constants over raw numbers; they are checked and self-explanatory.

Headers

Headers are name/value pairs. Names are case-insensitive (Content-Type and content-type are the same), and a name can appear more than once. The ones you meet daily:

  • Content-Type: what the body is (application/json, text/html; charset=utf-8).
  • Content-Length: body size in bytes.
  • Accept: which response formats the client understands.
  • Authorization: credentials, such as Bearer <token>.
  • Cookie and Set-Cookie: browser session state.
  • Cache-Control, ETag: caching rules.
  • Location: where to go next after a redirect or a 201 Created.
  • User-Agent, Origin, Host: who is asking and from where.

Axum represents them as HeaderMap, which stores lowercase names internally. You will extract them in headers, cookies and more extractors.

Bodies and content types

A body is raw bytes. The Content-Type header tells the receiver how to interpret them:

  • application/json: a JSON document. This is what most APIs use. See JSON and form bodies.
  • application/x-www-form-urlencoded: HTML form fields like name=Ada&age=36.
  • multipart/form-data: forms with file uploads.
  • text/plain, text/html: text.

If the client sends the wrong content type, a well-behaved server answers 415 Unsupported Media Type; if the body is the right type but invalid, 400 or 422. Axum's extractors do this for you through rejections.

A request/response cycle in order

sequenceDiagram
    participant C as Client
    participant S as Axum service
    C->>S: POST /notes (Content-Type: application/json, body)
    S->>S: route, extract JSON, run handler
    S-->>C: 201 Created, Location: /notes/7, body

The client sends a method, path, headers and body; the service answers with a status, headers and body.

Runnable models of the http types

The real http crate cannot run here, so these models copy its shape: a Method enum, a StatusCode with named constants and a reason phrase, and a header map that lowercases names.

Rust Stand-in: status codes and their classes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Rust Stand-in: a case-insensitive header map

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The real HeaderMap has the same behaviour: lowercase names, get for the first value and get_all for repeated headers such as Set-Cookie.

Common mistakes

  • Using GET for actions that change data. Crawlers and prefetchers issue GETs freely.
  • Returning 200 OK with an error message in the body. Use a proper 4xx/5xx so clients and monitoring can tell.
  • Confusing 401 and 403. 401 means "I do not know who you are"; 403 means "I know, and you may not".
  • Forgetting Content-Type. Without it clients must guess.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which HTTP method is both safe and idempotent?

    GET should not change state (safe), and repeating it has the same effect (idempotent). DELETE is idempotent but not safe.
  2. 2. Which status code best fits a successful creation of a new resource?

    201 Created tells the client a new resource exists, usually with a Location header pointing to it.
  3. 3. A client calls a protected route without credentials. Which status is conventional?

    401 means the request lacks valid authentication; 403 means authenticated but not permitted.
  4. 4. Are HTTP header names case-sensitive?

    Header names are case-insensitive; the http crate stores them in lowercase.

Summary

  • A request has a method, path, headers and body; a response has a status, headers and body.
  • Use the right method and status code: they are part of your API's contract.
  • Content-Type describes the body; extractors in Axum check it for you.
  • Axum re-exports Method, StatusCode and HeaderMap from the http crate as axum::http.

Next: Your First Axum Server