Design a small Python web API with explicit boundaries

Define one observable outcome

Start with a single sentence: “Given this request, return this response or one of these named failures.” Do not begin with routes, queues, or a framework comparison.

For example, a troubleshooting endpoint might accept a short issue description and return a category plus a reviewed playbook. Its contract should define required fields and limits, the response shape, repeat safety, dependency failures, and logging identifiers.

The FlyPython agent-loop example demonstrates the same principle without HTTP: the planner produces a bounded action, the runtime validates it, and only an allowlisted tool executes.

Validate at the first trusted boundary

JSON parsing only proves that the body is syntactically valid. Validate types, required fields, allowed values, and size before calling application logic.

Use consistent status semantics:

• 400 when the request itself cannot be interpreted;
• 401 or 403 for authentication or authorization failures;
• 404 when the addressed resource does not exist;
• 409 when the request conflicts with current state;
• 422 when a syntactically valid payload violates the input contract;
• 429 when a caller must slow down;
• 5xx when the service failed to fulfill a valid request.

Do not return 200 with { "error": ... }. It misleads clients, monitors, caches, and incident responders.

Bound every dependency

A request handler inherits the failure modes of every database, HTTP call, model, or queue it touches. Give each dependency a connection deadline, operation deadline, narrowly scoped retry policy, maximum response size, and sanitized error mapping.

The application-level deadline must leave enough time to return a controlled response. A loop counter is not a network timeout.

Test the contract, not the framework

Write tests for the smallest valid request, each validation boundary, a dependency timeout, malformed dependency data, an idempotent repeat, and an unexpected exception that does not leak secrets.

Keep domain rules in ordinary Python functions. Then most tests run without a server or network, while a smaller integration suite verifies HTTP serialization and status codes.

Define the production evidence

A deployment is not accepted because a process is listening. Verify the expected hostname, a version or commit marker, one healthy response, one controlled error, security headers, and logs for the same request identifier.

For public endpoints, document rate limits, maximum payloads, and contact information. For private endpoints, test authorization separately from authentication.

Sources

Status semantics are grounded in HTTP Semantics RFC 9110. The implementation references are FastAPI’s request-body validation and Python’s urllib.request.

Next, apply these boundaries to a repeated task in Build safe Python automation that can be retried.

Verification record

About the author

Practical Python guides researched, tested, and maintained by the FlyPython editorial team. Editorial standards and contact details →