Requests, Responses & HTTP

How does a Python program ask another system for something without sharing its memory or files?

By sending a message across an interface.

That sounds simple, but there are several layers hiding inside the phrase “call an API.” This lesson separates them before you write network code.

API does not automatically mean internet

An API is an interface that defines how software can interact with another piece of software.

Python itself exposes APIs. A class can expose an API. A library exposes functions and objects as an API. A web service can expose an API over a network.

Unit 13 focuses on web APIs reached through HTTP.

That distinction matters because these are not synonyms:

API   = interface / contract
HTTP  = network application protocol commonly used by web APIs
JSON  = one common representation for structured data

A web API might use HTTP and return JSON, but JSON is not the internet and HTTP responses are not required to contain JSON.

The request leaves your process

Imagine your script needs one user record.

Conceptually:

PYTHON PROGRAM
    |
    | HTTP request
    v
REMOTE SERVICE
    |
    | HTTP response
    v
PYTHON PROGRAM

Your program cannot reach into the server's variables. It sends a request that follows the service's published interface and receives a response.

Interactive model

Watch the HTTP round trip

Pause motionReset layout

The request leaves the Python client, the server processes it, the response returns to the client, and only then does Python parse the body into local data.

CLIENT Python program

HTTP REQUEST method · URL · headers

SERVER / API process request

HTTP RESPONSE status · headers · body

PYTHON DATA response.json() → dict/list

React Flow

Press enter or space to select a node. You can then use the arrow keys to move the node around. Press delete to remove it and escape to cancel.

Press enter or space to select an edge. You can then press delete to remove it or escape to cancel.

Drag nodes to inspect the relationships. Motion shows the active path; the plain background keeps attention on the relationships instead of graph-paper decoration.

View static diagram

Read that flow as a system boundary. The client controls the request it sends. It does not control whether the network is available, whether the remote service is healthy, or whether the response contains the shape of data it expected.

Anatomy of a request

A simplified HTTP request has several pieces.

Method

The method communicates the kind of operation being requested.

You will use GET first because it is commonly used to retrieve a representation of a resource.

Other methods exist for other interface semantics. Do not memorize a list yet. Learn to read the API's contract.

URL

A URL identifies where the request is sent and which resource/path is being addressed.

https://api.example.test/users/42
\___/   \______________/\_______/
scheme         host         path

A query string may add request parameters:

https://api.example.test/users?active=true

That is still part of the request target. It is not Python syntax.

Headers

Headers carry metadata about the request. They can describe accepted representation types, authentication information, client behavior, and other protocol details.

Never paste real credentials or tokens into course screenshots, examples, Git repositories, or public URLs.

Optional body

Some requests carry a body containing data. A simple GET request often does not need one.

Diagrams open at a readable shape-aware scale. Zoom or expand when you need more detail.

The response is a separate message

The server's response contains its own metadata and optional body.

STATUS
HEADERS
BODY

The status code reports the protocol-level result class.

Common families:

• 2xx — the request was handled successfully at the HTTP level;
• 3xx — further redirection or related action may be involved;
• 4xx — the request cannot be fulfilled as sent or authorized from the client side of the interaction;
• 5xx — the server reports that it failed to fulfill an otherwise received request.

Diagrams open at a readable shape-aware scale. Zoom or expand when you need more detail.

Do not reduce that to 4xx means you made a mistake. A 404 can happen because a resource no longer exists. A 401 or 403 can be an authorization boundary. The useful skill is reading the exact status in context.

A successful status does not prove your program is correct

Suppose the server returns:

200 OK

and the body is:

{
  "name": "Nova",
  "score": 850
}

Your request worked at the HTTP layer.

Your program can still fail later if it assumes a field named points:

print(data["points"])

That is now a data-contract problem, not an HTTP problem.

Keep the layers separate:

network/transport
        ↓
HTTP result
        ↓
body representation
        ↓
JSON parsing (if applicable)
        ↓
Python data structure
        ↓
application logic

Diagrams open at a readable shape-aware scale. Zoom or expand when you need more detail.

Predict the failure layer

For each situation, identify the earliest layer that failed.

Case A

The request times out before a response arrives.

That is not a JSON parsing failure. No response body arrived to parse.

Case B

The service returns HTTP 404.

The network and HTTP exchange happened. The result says the requested resource was not found.

Case C

The service returns HTTP 200 with an HTML error page instead of JSON.

The HTTP exchange can still be successful while your expected representation contract is wrong.

Case D

Valid JSON arrives, but the required key "completed" is missing.

Now the failure is in the data shape or application contract.

That classification will matter when you write exception handling. Catching every possible failure under one except: block erases useful evidence.

What to carry into Lesson 2

Before touching the requests package, you should be able to sketch this from memory:

CLIENT
  sends REQUEST
    method + URL + headers + optional body

SERVER / SERVICE
  sends RESPONSE
    status + headers + optional body

CLIENT
  validates the result before trusting the data

Lesson 2 turns that model into Python. Lesson 3 asks what happens when one of those layers stops behaving the way your program hoped.