First Server

Creating a Litestar application and serving a response

Concepts

A web server listens on a port for incoming network connections
- Your browser connects to it and sends an HTTP request
- The server sends back an HTTP response
- What happens between the moment a browser sends a request and the moment it displays a response?
A route maps a URL path like /snails to a Python function called a request handler
- The handler runs when a matching request arrives and returns the response
- What is a request handler and how does Litestar know which one to call for a given URL?
HTTP methods signal the client's intent
- GET retrieves data
- POST submits new data
- Choosing the wrong method breaks conventions and causes unexpected behavior
- What other HTTP methods are there besides GET and POST, and when should I use each one?
HTTP status codes communicate the outcome
- 200 means success
- 404 means the requested resource does not exist
- 500 means the server encountered an error
- What are the six most important HTTP status codes, and what does each one mean?
Requests and responses may have headers
- The Content-Type header tells the browser how to interpret the response body
- text/html triggers rendering as a page
- application/json means structured data
- What HTTP headers should I set in every server response, and what does each one tell the browser?
localhost (or 127.0.0.1) refers to your own machine
- Explain what localhost and 127.0.0.1 mean and how they differ from a real server address
The port number (e.g., 8000) identifies which program on that machine should receive the connection
- How do I choose a port number for a development server, and what numbers should I avoid?

A minimal Litestar app

One route
- Generate a minimal Litestar application with one route that returns "Hello, world"
One handler
- Explain what the @get decorator does in a Litestar handler function
Running on localhost
- How do I run a Litestar application and open it in my browser?
What the LLM generates and what the boilerplate actually does
- Explain each line of the Litestar boilerplate code you just generated

Routes and handlers

Path parameters
- Add a route with a path parameter to the Litestar application to get the current time
Query parameters
- Add an optional query parameter to a Litestar route and show how to read it in the handler
HTTP methods
- Show me how to define both a GET and a POST handler for the same URL path in Litestar
The difference between @get and @post, and when each applies
- What other decorators does Litestar provide and when should I use each?
HTTP versus HTTPS
- What are the important differences between HTTP and HTTPS?
- Why is this server using HTTP instead of HTTPS?

Returning plain text and JSON

Litestar's Response object
- Show me how to return a custom HTTP status code and headers from a Litestar handler
Automatic serialization of dicts and dataclasses to JSON
- Explain how Litestar automatically converts a Python dict or dataclass to JSON
What Content-Type headers are and why they matter
- What Content-Type header should I set when returning HTML versus JSON from a Litestar route?

Running and reloading

task run
- Write a taskipy task to start the Litestar development server
--reload mode
- Explain what --reload mode does and whether I should use it in production
Reading server logs
- What does each field in a Litestar server log line mean?
Common startup errors and how to interpret them
- What are common reasons a Litestar server fails to start, and how do I read the error message to diagnose the problem?

The request-response cycle

What happens between browser and server
- Describe each step that happens between a user clicking a link and the browser displaying the new page
Where the LLM's code fits into that picture and what it does not handle
- In the request-response cycle, what parts does Litestar handle automatically and what parts do I need to write myself?

Check for Understanding

What does it mean for a server to "listen on port 8000"?

The operating system assigns each network service a port number. When a server "listens on port 8000", it registers with the OS to receive any incoming network connections directed at that port. Your browser connects to http://localhost:8000 by opening a connection to port 8000 on the local machine.

If you define two routes with the same path but different HTTP methods, will Litestar treat them as one route or two?

It will treat them as two separate routes. A route in Litestar (and in HTTP in general) is identified by both the path and the method. GET /snails and POST /snails are distinct routes that can have completely different handlers. This is normal: GET might retrieve a list, while POST creates a new item.

What happens in the browser if the server returns Content-Type: application/json but you expected HTML?

The browser will not render the response as a page. Depending on the browser, it will display the raw JSON text, offer to download it, or show it in a JSON viewer. The Content-Type header is how the browser decides what to do with the response body, so returning the wrong one produces confusing results.

Why does --reload mode watch for file changes, and why would you not use it in production?

In development, --reload restarts the server automatically whenever you save a file, so you do not have to stop and restart manually after every change. Automatic restarts are dangerous in production: a partial file save or a syntax error could take the server down, and the restart overhead adds latency. Production servers use a process manager that restarts only on deliberate deployments.

Exercises

Add a health-check route

Add a /health route that returns a JSON object containing the current server time. Confirm it works by visiting it in a browser and with curl. Prompt the LLM to write the handler, then read the code and identify which part produces the timestamp and which part controls the response format. Did you prompt the LLM to write the curl command?

Add a path parameter

Prompt the LLM to add a route /site/{site_name} that extracts the site name from the URL and returns it in a plain-text response. Try visiting /site/toronto in your browser and verify the response contains the name. What happens if you visit /site/ with no name?

Explore error handling

Visit a URL that is not handled by any route (e.g., /does-not-exist). Note what Litestar returns by default. Ask the LLM to add a custom 404 handler that returns a friendlier error message. Verify it works and check that it also sets the correct status code.

Read the server log

Run the server and make at least four requests: a successful GET, a 404, a route with a path parameter, and a request with a query parameter. For each line the server prints, write a one-sentence explanation of what it records, then compare your explanation with one from an LLM.