API Testing

API testing

An HTTP API is a contract you cannot redeploy in lockstep with its clients. When the status code, the JSON shape, or the 401-versus-403 distinction drifts, every caller breaks at once and you learn about it from their incident reports. Testing at the boundary means sending real requests over HTTP and asserting the whole response, so a contract change fails your build instead of a customer's.

Method

1. Assert the whole response, not just the happy body. Check status code, key headers (Content-Type, Location, Cache-Control), and the body together. A 200 with correct JSON but a missing Content-Type: application/json still breaks strict clients.
2. Validate the body against a schema, not field by field. Pin the payload to a JSON Schema, an OpenAPI component, or a pydantic model and validate against it. This catches an added null field or a widened type that ad hoc assert body["id"] == 5 never sees.
3. Test error responses as hard as success. Drive 400, 401, 403, 404, 409, and 422 deliberately: malformed JSON, missing field, duplicate key, unknown id. Assert the error body shape (code, message, field) so clients can branch on it, not just the status.
4. Walk every auth path. Send no token, an expired token, a valid token with the wrong scope, and a valid token. Assert 401 for absent or bad credentials and 403 for authenticated-but-unauthorized: collapsing the two leaks whether a resource even exists.
5. Hit the real HTTP boundary. Use httpx, requests, supertest, or the framework's test client against a running app so routing, middleware, content negotiation, and serialization all run. Calling the handler function directly skips exactly the layers that break.
6. Pin the contract against the published spec. Validate responses against the checked-in OpenAPI document, or run consumer contract tests with Pact, so a schema change that no test named still fails the build before it ships.

Checks

• Would a widened type or an extra field in the response body fail a test?
• Does an unauthenticated request get 401 and an unauthorized one 403, each asserted separately?
• Do malformed and conflicting requests return the documented error shape, not a bare 500?

Boundaries

This covers one service at its HTTP edge. Cross-service journeys belong to integration-testing, full user flows to e2e-testing, and the persistence layer beneath the handler to database-testing. Follow the project's existing client and schema tooling rather than adding a second assertion style.