FDE Times dataFDE jobs open 924▲33 Change in open roles over 7 days, like-for-like: roles from companies we started tracking this week are left outNew in 7 days 80Companies hiring 196Remote-friendly 25%Median US pay $200kTop hirer Databricks 107
中文VI

The newspaper of the Forward Deployed Engineer

Guides

Stop a customer's bad JSON at the client, then test it offline

Swap only the transport, and the same client calls the real API and runs its tests offline, with no code changes.

ShareLinkedInFacebookX

In brief

  • Keep exactly one httpx.Client inside the client, as the httpx docs advise, set base_url to keep calls short, and choose the timeout yourself rather than relying on the 5-second default.
  • Validate responses with Pydantic: a bad payload raises ValidationError right at the client, and the error names the field at fault.
  • Let the client accept a transport from outside. MockTransport then lets the tests run entirely offline without changing any code.
Diagram: OrdersClient calls httpx.Client, which passes through a transport layer highlighted in orange. The layer branches to HTTPTransport when calling the customer's real API, or to MockTransport when running tests without a network. OrdersClient and httpx.Client stay unchanged in both cases.
The same OrdersClient can call the real API and run offline tests. To switch between the two modes, simply pass httpx.MockTransport(handler) to the transport parameter.

In your first week on a customer site, the thing you touch most is usually their internal API: poorly documented, slow, and now and then returning JSON that does not match its description. If your code reads resp.json()["total"] all over the place, one missing field is enough to break the demo. And the stack trace then points to a line buried three layers deep.

This guide helps you avoid that with a small, typed Python client built on httpx and Pydantic, plus a test suite that needs no network. You will work with a hypothetical orders API that has an /orders/{id} endpoint. The orders API is invented, but every function and class used here appears in the official documentation of httpx, Pydantic and pytest.

You need Python 3, a virtualenv and a few minutes of setup:

pip install httpx pydantic pytest

Step 1: write the data contract as a model

Before calling the network, write down what you believe the API will return. This model is the contract between your code and the customer’s system.

# orders_client/models.py
from pydantic import BaseModel

class Order(BaseModel):
    id: int
    status: str
    total: float

According to the Pydantic documentation, whenever data does not match the model the library raises ValidationError. Conversely, when validation succeeds, Pydantic guarantees that the object’s fields match the declared types. The client in this guide relies on that guarantee, so downstream code no longer has to wonder whether total exists.

Check: in a REPL, call Order.model_validate_json('{"id": 1, "status": "new"}'). You should see a ValidationError with one error entry of type missing, the message Field required, and total as the first element of loc.

Step 2: why have only one httpx.Client?

Many people call httpx.get() directly in every function. That works, but the httpx documentation is clear: for anything beyond experimentation, one-off scripts or prototypes, use a Client instance. So a client for the customer’s API should hold exactly one httpx.Client and reuse it for every request.

# orders_client/client.py
import httpx
from .models import Order

class CustomerApiError(Exception):
    def __init__(self, status_code: int, body: str):
        super().__init__(f"Customer API returned {status_code}: {body[:200]}")
        self.status_code = status_code
        self.body = body

class OrdersClient:
    def __init__(self, base_url: str, transport=None, timeout: float = 10.0):
        self._http = httpx.Client(
            base_url=base_url, timeout=timeout, transport=transport
        )

    def get_order(self, order_id: int) -> Order:
        resp = self._http.get(f"/orders/{order_id}")
        try:
            resp.raise_for_status()
        except httpx.HTTPStatusError as exc:
            raise CustomerApiError(exc.response.status_code, exc.response.text) from exc
        return Order.model_validate_json(resp.content)

    def close(self) -> None:
        self._http.close()

Three decisions in this code deserve attention. The first is base_url: httpx prepends this URL to every request, so each method only passes a path. To move from staging to production, you change a single string.

The second is the timeout. By default httpx raises TimeoutException when the network stays silent for more than 5 seconds. That may be too short for a long-running report, or too long for an endpoint that ought to answer immediately.

Here the timeout is written out so that anyone reading the code understands it is a deliberate choice, not a forgotten default. The 10 seconds is only for illustration; for the real value, ask the customer for the endpoint’s SLA.

The last decision is raise_for_status(). It turns every response outside the 2xx range into an HTTPStatusError, which carries both the request and the response. The client converts it into CustomerApiError, so for HTTP errors the layers above catch a project error instead of having to know about httpx’s error classes.

The limits of this cut-down version should be stated plainly: ValidationError and httpx.TimeoutException still go straight up to the caller. ValidationError is left alone on purpose, so the tests in Step 4 show the bad payload clearly. In a real project you can wrap these two as well into your own errors; only then do the upper layers truly need to catch nothing but project errors.

Check: get_order returns an Order, not a dict. Your editor can now autocomplete .total.

Step 3: what is the transport parameter for?

Note the transport=None parameter in the constructor, because this is what lets the tests run offline. According to the httpx documentation, MockTransport takes a handler function that maps each request to a predefined response. No real request leaves the machine.

Wiring it in is simple too, because httpx.Client already accepts a transport parameter: pass in httpx.MockTransport(handler) and you are done. The code under test stays the same; only the transport layer underneath is swapped.

James Bennett, in his post “Don’t mock Python’s HTTPX”, recommends exactly this: use HTTPX’s built-in mock transport rather than mocking HTTPX itself or its internals, to reduce dependence on mock objects and avoid a lot of trouble.

# tests/test_client.py
import httpx
import pytest
from pydantic import ValidationError
from orders_client.client import OrdersClient, CustomerApiError

def handler(request: httpx.Request) -> httpx.Response:
    if request.url.path == "/orders/42":
        return httpx.Response(200, json={"id": 42, "status": "shipped", "total": 19.5})
    if request.url.path == "/orders/7":
        return httpx.Response(200, json={"id": 7, "status": "shipped"})
    return httpx.Response(404, json={"error": "not found"})

@pytest.fixture
def client():
    c = OrdersClient("https://api.customer.example", transport=httpx.MockTransport(handler))
    yield c
    c.close()

In pytest, a test function gets a fixture simply by declaring it as a parameter. Every test therefore shares a client running on the mock without repeating the setup.

Step 4: test all three outcomes, not just the happy path

A client calling into a customer’s system has at least three outcomes: correct data, data of the wrong shape, and an HTTP error. Each needs its own test.

def test_order_ok(client):
    order = client.get_order(42)
    assert order.total == 19.5

def test_payload_missing_field(client):
    with pytest.raises(ValidationError):
        client.get_order(7)

def test_404_becomes_custom_error(client):
    with pytest.raises(CustomerApiError) as exc:
        client.get_order(999)
    assert exc.value.status_code == 404

Look closely at order 7. The API returns status 200, which looks like success, but total is missing. Without a model, the error only surfaces when some revenue function somewhere hits a KeyError.

With a model, get_order(7) stops immediately with a ValidationError, and the error entry names the total field with the message Field required. You know at once which field broke, and on which endpoint.

Check: turn off Wi-Fi and run pytest -q. All three tests should still pass.

When should you move to pytest-httpx?

A hand-written handler is easy to follow, but it has a blind spot: if you prepare a response for a path the code never calls, the test still passes. pytest-httpx closes this gap. According to its documentation, a test fails at teardown if any registered response was never requested.

By default, pytest-httpx also immediately raises httpx.TimeoutException for any request that matches no registered response, so a test cannot quietly call out to the real network. Redowan Delowar also mentions respx, a library that intercepts httpx requests during tests and returns prepared responses. Both add a dependency; for a small client in your first week, the built-in MockTransport is enough.

Common mistakes

The most common mistake is creating a new httpx.Client in every method or every loop iteration. That goes against the httpx documentation’s advice, and base_url and the timeout end up scattered, so switching environments or adjusting the timeout means editing many places.

The second is catching a bare Exception and returning None. The client then swallows both ValidationError and HTTPStatusError, and you will lose an afternoon working out why the dashboard is empty.

The third is making the model too strict on day one, before you have seen real data. Run the client against a few real payloads from staging, then tighten the model gradually.

How this helps on a customer site

When a deployment starts, write this client as early as possible, because it decides where errors will surface later.

If the customer changes the schema without warning, the ValidationError test and the error log at the client let you point straight at the problem: “the total field has been missing since yesterday’s release”.

The offline test suite also lets you keep working when you do not yet have VPN access or credentials, or when the customer’s staging is down.

If you are aiming for an FDE role, put a repo like this in your portfolio: a typed client for a public API, with tests covering all three outcomes. On a CV, writing “typed client with offline tests for bad payloads and 4xx codes” is more convincing than “experience integrating APIs”.

The customer’s system will keep changing. What you control is where errors surface, and the best place is right at the client.

Was this article useful?

Use with your AI assistantAsk Claude ↗Ask ChatGPT ↗
10 sources
Read next on the roadmap · Stage 1: FoundationsA service that runs fine today can die at the first rebootThe cause usually sits in three lines of systemd configuration, and the evidence may vanish with the restart itself.