Flask / HTTP / curl

The web is a two-way conversation

HTTP (Hypertext Transfer Protocol) runs the show. Strict turn-taking: the client speaks first, the server answers once, and the round is over.

one request → one response → done · every click, refresh and API call is exactly this

Why HTTP exists

Before HTTP, every client–server pair invented its own dialect. HTTP is the one dialect everyone agreed on.

Client vs server — the only two roles

Every web app you'll ever ship is these two roles talking. This course is about becoming the person who builds the right side.

What happens when you click a link

Four beats, half a second. Everything in this course is a zoom-in on one of these beats.

1. 1

   You click

   The browser decides 'I need that address' and builds a request: URL, method (GET), headers — a small text message.

2. 2

   It travels

   The request rides the network to the right machine, the right port. (TLS encrypts the trip — a later topic.)

3. 3

   The server works

   The server hands the request to your app. The app does the job: reads data, runs logic, builds a page or JSON.

4. 4

   You see pixels

   The response rides back. The browser parses the HTML, applies the CSS, runs the JS, paints. Done — until the next click.

A request is four parts

Everything a client can say, packed into one message. No more, no less.

A real exchange, no browser in sight

This is literally what travels between client and server. Left: the request (method + URL + headers + body). Right: the response (status + headers + body).

GET /users/42?sort=new HTTP/1.1
Host: api.shop.com
Content-Type: application/json

{"name": "Ada"}

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 46

{"id": 42, "name": "Ada", "posts": 3}

Anatomy of an address

Every URL is five jobs in one line. Browsers and servers split it apart the same way every time.

https://api.shop.com:8443/users/42?sort=new&page=2

scheme   https          how to talk
host     api.shop.com   which machine answers
port     :8443          which door (80 and 443 are the defaults)
path     /users/42      which resource
query    ?sort=new...   options, as key=value pairs

Most of the time the port is hidden — :80 for http, :443 for https are implied.

A response is three parts

Mirror image of the request — but it starts with a verdict: the status code.

Methods — the verbs of the web

The method is a promise about intent. You and the server can rely on it: GET never changes anything, POST creates, DELETE removes.

Choosing the right verb

Pick by intent, not by habit. The method tells caches, browsers and other apps how safe it is to touch your endpoint.

Status codes — the server's one-line answer

Every response starts with a 3-digit number. The first digit tells the whole story at a glance.

The nine codes you'll actually meet

Memorize the pattern, not the list: 2xx done, 3xx go elsewhere, 4xx your problem, 5xx ours.

401 vs 403 — identity, then permission

The most confused pair in HTTP. 401 is an identity problem; 403 is a permission problem.

The four headers that answer the common questions

There are ~100 headers in total. These four answer the questions that come up most often.

The redirect dance

A redirect isn't an error — it's a signpost. You never write it, you just watch it happen.

1. 1

   You ask for the old address

   GET /old-page. The server knows it moved — but it doesn't send the page, it sends a signpost.

2. 2

   The server points

   301 + a Location header: /new-page. One tiny response, no content — just 'go there instead'.

3. 3

   The browser obeys automatically

   It re-requests the new URL, gets 200, and shows the page. From your seat, it felt like one click.

What a web server actually does

Strip away the marketing: a web server is a program looping through four steps, thousands of times per second.

1. 1

   Listen on a port

   It waits on a port (80 for HTTP, 443 for HTTPS) for incoming connections — a phone left off the hook.

2. 2

   Parse the request

   It decodes the bytes into method, URL, headers, body — the four parts from earlier.

3. 3

   Run your code

   It hands the request to your application (Flask, in this course), which decides what to do — usually: read some data, build a page.

4. 4

   Send the response

   It wraps the result in status + headers + body and ships it back. Then back to step 1.

A port is a door number

One machine runs many services; the port picks the door. Production answers at 80/443; your Flask dev server usually opens 5000.

Flask, in four sentences

A framework is scaffolding you don't have to build. Flask is the lightest popular scaffolding for Python web apps.

A whole website, 8 lines

This is a complete, runnable web app. Two routes: one for humans (HTML), one for programs (JSON).

from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/")
def home():
    return "<h1>Hello, shipper!</h1>"

@app.route("/api/hello")
def api_hello():
    return jsonify(name="shipper", status="alive")

Run it with flask run, open http://127.0.0.1:5000 — that's the entire server side of a web app.

Two terminals, zero browsers

That's the whole loop: Python on your machine answering HTTP on a port. You can test it before a human ever sees it.

Routes up close

Once you know the promise, routes are just sign-up forms. Four details worth knowing.

Three ways to answer

Same app, three return styles. The return value decides what the client receives — and at which status code.

from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/")
def page():
    return "<h1>Hello, shipper!</h1>"   # -> text/html

@app.route("/api/hello")
def api():
    return jsonify(name="shipper")      # -> application/json

@app.route("/missing")
def gone():
    return "not here", 404               # -> you pick the status

One rule to remember: whatever the function returns, Flask wraps into status + headers + body.

HTML for eyes, JSON for machines

One app usually does both: HTML routes for people, /api routes for programs.

Four doors the client can knock on

Clients send data in different shapes; Flask exposes each one in a different place. Learn where to look and the syntax follows.

from flask import request

@app.route("/users/<int:uid>")       # 1. URL parameter
def show_user(uid):
    return jsonify(uid=uid)

@app.route("/search")
def search():
    q    = request.args.get("q")    # 2. query string: /search?q=shoes
    name = request.form.get("name") # 3. form field (login, checkout...)
    body = request.json              # 4. JSON body (from an API client)

One app, four ways in. <uid> comes from the URL; the rest live on the request object.

Where each kind of data lands

Matching the channel to the job is the whole design decision behind every API.

Reading the query string, safely

Query values arrive as strings — even '42'. Set defaults, and convert types yourself.

@app.route("/search")
def search():
    q = request.args.get("q", "")              # ?q=shoes -> "shoes", else ""
    page = request.args.get("page", 1, type=int)  # ?page=2 -> 2 (an int)
    if not q:
        return "nothing to search", 400
    return jsonify(q=q, page=page)

get(key, default, type=...) is the 90% solution for query strings.

Inside a Flask request

Four stops between 'bytes arrive' and 'bytes leave'. Knowing the route makes debugging 10x faster.

1. 1

   The server receives

   The web server (or Flask's dev server) gets the raw HTTP bytes and hands them to Flask.

2. 2

   Flask matches the route

   It walks your registered promises: method + URL. No match? Instant 404 — your code never runs.

3. 3

   Your function runs

   The view function reads the input (args, form, json), does the work — often: fetch data — and returns a value.

4. 4

   Flask wraps and sends

   The return value becomes status + headers + body, and rides back to the client. The round trip is over.

Errors are just status codes

Flask's dev server shows the full traceback on 500s — the last line usually names the exact bug. Fix, save, curl again.

Returning errors on purpose

A correct app fails politely: the right code tells the client exactly what to try next.

Why developers live in curl

curl is the browser's blunt, honest cousin: it shows the plumbing the browser hides.

One app, four answers

Success, data, filtered data, failure. This is what testing an API feels like.

Six flags, 95% of API testing

curl's default is: GET a URL and print the body. The flags bend it into a full API client.

Create a record from the terminal

Method + header + body + URL. This one pattern covers most of the 'send data to my API' work.

# the classic "create a record" one-liner
curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{"name": "Ada"}' \
  http://127.0.0.1:5000/users

# ...and check what the server actually said
curl -i -X POST \
  -H 'Content-Type: application/json' \
  -d '{"name": "Ada"}' \
  http://127.0.0.1:5000/users

With -i you should see HTTP/1.1 201 CREATED — proof the record was born.

-v: watch the conversation happen

Lines starting with > are yours; lines starting with < are the server's. This is the whole protocol, live.

The whole stack in one picture

Three roles, one pipeline — and the next topic (nginx) plugs in right here.

clients talk to the door · the door talks to the app · the app talks to the world — all in plain HTTP