Making HTTP POST Requests with Httpx in Python

The Httpx library in Python provides a modern and intuitive HTTP client for making requests. One common task is making POST requests to submit data to APIs and web services. In this guide, we'll walk through how to properly structure POST requests with Httpx.

Creating the POST Request

To start, we need to import Httpx and structure our basic POST request:

import httpx

data = {
    "name": "John Doe",
    "email": "john@example.com"  
}

r = httpx.post("https://example.com/users", json=data)

Here we have a dictionary data containing the data we want to submit, which we pass to the .post() method using the json parameter. This will properly encode the body and headers for us.

Handling the Response

Once we have made the request, we likely want to check the status code and potentially access the response data:

if r.status_code == httpx.codes.CREATED:
    print(r.json())
else:
    print("Error, got status", r.status_code)

This checks if we get a 201 Created successful response, prints any JSON response data, and handles any errors.

Adding Request Headers

APIs often require additional headers to be set like authentication, content type, etc. We can easily add these with Httpx:

headers = {
    "Authorization": "Bearer mytoken",
    "Content-Type": "application/json" 
}

r = httpx.post("https://api.example.com/users", json=data, headers=headers)

Posting Form Data

In addition to JSON, you may need to POST traditional form data. This can be done by passing a dictionary to the data parameter instead:

data = {
    "name": "John Doe",
    "email": "john@example.com"
}

r = httpx.post("https://example.com/users", data=data)

Posting Multipart Form Data

Httpx also supports posting multipart form data, like file uploads. First we need to encode the data, then pass it to .post():

data = {
    "profile_pic": ("image.jpg", open("image.jpg", "rb"), "image/jpeg") 
}

r = httpx.post("https://example.com/upload", files=data)

This opens and uploads the image.jpg file.

Timeouts, Retries and Error Handling

Additional options like timeouts and retries can be set on the client for dealing with errors and latency:

client = httpx.Client(timeout=10.0, retries=3)

try:
    r = client.post(url, data=data)
    r.raise_for_status()
except httpx.TimeoutException:
    print("Request timed out!")
except httpx.HTTPStatusError:
    print("Error response")

Here we handle common exceptions from Httpx when making the request.

This covers the key patterns for making POST requests with Httpx for calling APIs and submitting data. The client handles encoding, validation, authentication, timeouts and more, making it a robust HTTP client option for Python.