Programming languages · Beginner · 18 min
How to Call a Web API from Python with httpx
By Padding · Updated 15 Nov 2026
Python 3.15 · httpx 0.28
You will install httpx 0.28, write a small local API to practise on, then call it from Python by fetching JSON, add query parameters and a reusable client, handle bad statuses, timeouts and network failures, send JSON in a POST request, and make several requests at once with async code.
On this page
A web API is a program on another computer that answers requests over HTTP and usually replies with JSON. Python can call one in a few lines. The library you will use is httpx, a modern HTTP client with a simple API, sensible handling of timeouts and an async version built in. It is a package from PyPI, so you install it into a project environment as in the previous tutorial.
To practise without depending on anyone else's server, you first write a tiny API of your own with Python's standard library. It runs on your machine at 127.0.0.1:8000, answers with JSON, can be made to respond slowly, and returns a 404 for things that do not exist. Everything that follows works the same against a real service. A final optional step shows a call to a public API.
Step 1 · Create a project and install httpx
Create a project folder and add httpx. The version range allows patch updates of 0.28 and nothing newer, so a new minor release cannot change behaviour under you:
mkdir -p ~/api-demo
cd ~/api-demo
uv init --no-package
uv add "httpx>=0.28,<0.29"uv creates the project's .venv, installs httpx with its dependencies, and records the range in pyproject.toml.
Check it worked
uv run python -c "import httpx; print(httpx.__version__)"The command prints 0.28.1, or a later 0.28 release.
Step 2 · Write a practice API
Create server.py. It keeps a list of notes in memory and has four routes: a list with an optional limit, one note by ID, a POST that adds a note, and a slow route that waits before it answers. It uses only the standard library, so there is nothing more to install:
cat > server.py <<'PY'
import json
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.parse import parse_qs, urlparse
NOTES = [
{"id": 1, "title": "Install Python", "done": True},
{"id": 2, "title": "Install httpx", "done": False},
{"id": 3, "title": "Call an API", "done": False},
]
class Handler(BaseHTTPRequestHandler):
def send_json(self, status, payload):
body = json.dumps(payload).encode()
self.send_response(status)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(body)))
self.end_headers()
self.wfile.write(body)
def do_GET(self):
url = urlparse(self.path)
query = parse_qs(url.query)
if url.path == "/api/notes":
limit = int(query.get("limit", [len(NOTES)])[0])
return self.send_json(200, NOTES[:limit])
if url.path.startswith("/api/notes/"):
wanted = url.path.rsplit("/", 1)[1]
for note in NOTES:
if str(note["id"]) == wanted:
return self.send_json(200, note)
return self.send_json(404, {"error": "no such note"})
if url.path == "/api/slow":
delay = float(query.get("delay", ["3"])[0])
time.sleep(delay)
return self.send_json(200, {"waited": delay})
self.send_json(404, {"error": "not found"})
def do_POST(self):
if self.path != "/api/notes":
return self.send_json(404, {"error": "not found"})
length = int(self.headers.get("Content-Length", 0))
try:
data = json.loads(self.rfile.read(length))
except ValueError:
return self.send_json(400, {"error": "send JSON"})
note = {"id": len(NOTES) + 1, "title": data.get("title", ""), "done": False}
NOTES.append(note)
self.send_json(201, note)
def log_message(self, format, *args):
pass
ThreadingHTTPServer(("127.0.0.1", 8000), Handler).serve_forever()
PYStart it in the second terminal, from the same folder, and leave it running:
uv run server.pyThe server prints nothing, because the script switches request logging off. Run the next commands in your first terminal. This is a toy: it has no authentication, keeps data only in memory and is not meant for anything but practice.
Step 3 · Make your first request
Write a script that fetches one note and prints the pieces you care about:
cat > first.py <<'PY'
import httpx
response = httpx.get("http://127.0.0.1:8000/api/notes/1")
print(response.status_code)
print(response.headers["content-type"])
note = response.json()
print(note["title"], note["done"])
PY
uv run first.pyhttpx.get sends a GET request and returns a Response. The status code says how it went, 200 meaning success. response.headers is a case-insensitive mapping, and response.json() parses the body as JSON into Python dictionaries and lists, just as json.loads does.
Check it worked
The output is three lines: 200, application/json, and Install Python True.
Step 4 · Add parameters, headers and a reusable client
Each httpx.get call opens a new connection. When you make several requests to one service, use a Client. It keeps connections open and holds settings you would otherwise repeat: the base address, headers and a timeout.
cat > client.py <<'PY'
import httpx
with httpx.Client(
base_url="http://127.0.0.1:8000",
headers={"Accept": "application/json"},
timeout=10.0,
) as client:
response = client.get("/api/notes", params={"limit": 2})
response.raise_for_status()
print(response.url)
for note in response.json():
print(note["id"], note["title"])
PY
uv run client.pyparams builds the query string for you, with correct escaping, so you never join strings by hand. The with block closes the client when it ends. The timeout=10.0 means each phase of a request, such as connecting or waiting for data, may take up to ten seconds before httpx gives up. httpx has a five-second default timeout, but writing your own value makes the choice visible. A request with no timeout can hang a program forever.
Check it worked
The first line is the full address, http://127.0.0.1:8000/api/notes?limit=2, followed by 1 Install Python and 2 Install httpx.
Step 5 · Handle failures
Requests fail in three different ways, and httpx has a different exception for each:
- The server answers with an error status, such as
404. httpx does not raise on its own, so callresponse.raise_for_status(), which raiseshttpx.HTTPStatusErrorfor any4xxor5xx. - The server takes too long:
httpx.TimeoutException. - The request never reaches a server, because of DNS, a refused connection or a network error:
httpx.RequestErroris the base class for all of those, andTimeoutExceptionis one of its subclasses.
Order the except clauses from most specific to most general:
cat > errors.py <<'PY'
import httpx
def fetch(url, timeout=5.0):
try:
response = httpx.get(url, timeout=timeout)
response.raise_for_status()
return response.json()
except httpx.HTTPStatusError as err:
print("bad status:", err.response.status_code)
except httpx.TimeoutException:
print("timed out")
except httpx.RequestError as err:
print("network problem:", type(err).__name__)
fetch("http://127.0.0.1:8000/api/notes/99")
fetch("http://127.0.0.1:8000/api/slow?delay=3", timeout=1.0)
fetch("http://127.0.0.1:9/")
PY
uv run errors.pyThe three calls trigger one failure each. The first asks for a note that does not exist. The second asks the slow route to wait three seconds, so a one-second timeout expires first. The third connects to port 9 on your own machine, where nothing listens.
Check it worked
The output is bad status: 404, timed out and network problem: ConnectError.
Troubleshooting
If every call prints network problem: ConnectError, the practice server is not running. Start it in the second terminal and run the script again. If the second call prints network problem and not timed out, check that nothing else is using port 8000. For real services, httpx reads the standard HTTP_PROXY and HTTPS_PROXY environment variables, so a proxy can also cause connection errors.
Step 6 · Send data with POST
To send JSON, pass a Python dictionary as json=. httpx turns it into JSON text and sets the Content-Type header. The practice server adds the note and answers 201 Created with the new record:
cat > post.py <<'PY'
import httpx
payload = {"title": "Buy milk"}
response = httpx.post("http://127.0.0.1:8000/api/notes", json=payload, timeout=10.0)
response.raise_for_status()
print(response.status_code)
print(response.json())
PY
uv run post.pyCheck it worked
The output is 201 and {'id': 4, 'title': 'Buy milk', 'done': False}. Use data={...} instead of json= for classic form-encoded bodies, and files= for uploads.
Step 7 · Make requests at the same time
A normal call waits for the answer before the next line runs. When you need several independent answers, the time adds up. httpx also has an async client. With Python's asyncio, the waits overlap. Ask the slow route for three one-second waits at once and time the result:
cat > parallel.py <<'PY'
import asyncio
import time
import httpx
async def wait_one(client, number):
response = await client.get("/api/slow", params={"delay": 1})
response.raise_for_status()
return number
async def main():
started = time.perf_counter()
async with httpx.AsyncClient(base_url="http://127.0.0.1:8000", timeout=10.0) as client:
results = await asyncio.gather(*(wait_one(client, n) for n in (1, 2, 3)))
elapsed = time.perf_counter() - started
print(results)
print("under two seconds:", elapsed < 2)
asyncio.run(main())
PY
uv run parallel.pyasync def defines a function that can pause at each await. asyncio.gather starts all three requests and returns the results in the order you passed them, once every one is done. Three one-second waits take about one second in total, not three. Use AsyncClient only inside async code. In an ordinary script, the plain Client is simpler and just as correct.
Check it worked
The output is [1, 2, 3] and under two seconds: True.
Step 8 · Optional, call a real API
Everything above works against a public API by changing the address. The GitHub REST API needs no account for public data. This call is not part of the practice setup, because it depends on a service you do not control:
uv run python -c "import httpx; r = httpx.get('https://api.github.com/repos/encode/httpx', timeout=10.0); print(r.status_code, r.json()['full_name'])"It prints 200 encode/httpx. Unauthenticated requests are limited to a small number per hour per IP address, and over the limit you get a 403 or 429 status, so wait and retry. To send a token, read it from an environment variable, and never write it into a script or pass it on a command line.
Step 9 · Clean up
Stop the practice server with Ctrl+C in the second terminal. Then remove the demo project. Python and uv stay installed:
cd ~
rm -rf ~/api-demoNext steps
- Check code that talks to an API without calling the real one: write and run tests with pytest.
- Save what you fetch: read and write files and JSON.
- The httpx documentation at python-httpx.org covers authentication, redirects, retries through transports, streaming downloads and HTTP/2.
Related tutorials
- How to Use Virtual Environments and Install Packages in PythonYou will create an isolated Python 3.15 environment for a project, install a package into it with pip, record the exact versions, rebuild the environment from that record, and then manage the same project with uv.
- How to Read and Write Files and JSON in PythonYou will read and write text files with pathlib, convert Python data to JSON and back, and use both to build a small task list that keeps its data in a JSON file and survives a damaged file.
Need this done for you?
Padding does this work for growing companies, from the first diagnosis to a system that keeps working.
Get new tutorials