Production Python & APIs

See the system

Build small services with explicit contracts, predictable failures, and tests that reveal real defects.

Separate transport from business logic

Keep request parsing, business decisions, and external integrations in separate modules. Your HTTP handler should validate input and call an application function. A model adapter should hide provider details behind a small contract so a fake can exercise failure paths in ordinary tests.

This separation makes changes cheaper: a provider SDK upgrade should not rewrite the approval policy. Prefer a small, well-defined interface to an elaborate abstraction that supports hypothetical future systems.

Validate at every trust boundary

A type annotation helps readers and tools; it does not automatically validate an HTTP request at runtime. Check field types, maximum sizes, required identifiers, and allowed values. Reject unexpected state transitions on the server, even if the user interface disables the corresponding button.

Treat model output as untrusted input too. Parse a structured response, validate its schema, and apply domain rules before displaying or acting on it. Return stable error categories rather than leaking internal exceptions.

Make failure behavior intentional

Every remote call needs a timeout. Retry only when the failure is transient and repeating the operation is safe. A read may be retried; a payment or ticket write needs an idempotency contract. Use bounded exponential backoff and account for the overall user-request deadline.

Concurrency improves I/O throughput but can overload a provider or exhaust connections. Bound it, propagate cancellation where supported, and distinguish a slow response from a permanently invalid request.

Test behaviors and boundaries

Unit tests cover isolated rules. Contract tests verify an adapter’s request and response assumptions. Integration tests exercise real component boundaries. End-to-end tests check a critical user journey. Each has different cost and diagnostic value.

A test that simply repeats the implementation is weak. Use realistic counterexamples: empty input, a forbidden document, duplicate requests, a timeout, and a changed response schema. Keep ordinary tests deterministic with controlled fixtures.

Make the service observable and reproducible

Use structured events with request IDs, stage names, durations, and stable error codes. Avoid logging raw prompts or customer records by default. Store configuration outside code and fail clearly when required settings are missing.

Pin the tested dependency environment, document the interpreter version, and give a clean setup command. A colleague should be able to reproduce a failure without guessing which package versions or hidden files you used.

Worked scenario

A document API initially catches every exception and returns an empty answer. Users cannot distinguish “no evidence” from “provider unavailable.” Replace this with separate no-evidence, invalid-request, forbidden, and upstream-unavailable outcomes. Test that internal stack traces never become API responses.

A small example

This example isolates one concept. Read its boundary conditions before adapting it to an application.

from dataclasses import dataclass

@dataclass(frozen=True)
class Question:
    text: str

    def __post_init__(self):
        if not isinstance(self.text, str):
            raise TypeError("text must be a string")
        if not 1 <= len(self.text.strip()) <= 2000:
            raise ValueError("question length must be 1..2000")

print(Question("Where is the leave policy?"))

Practical assignment

1. Run the reference lab tests.
2. Trace the public function through retrieval and response assembly.
3. Add a maximum question length validation.
4. Add an invalid-input test and a timeout-adapter design.
5. Document error categories and retry rules.
6. Review logs for sensitive data before submission.

What to submit

Submit the artifacts named above, a short explanation of your decisions, and evidence of the checks you performed. Distinguish measured results from estimates and designs from executed integrations.

Knowledge check

References & next step

Platform examples are environment-dependent. Start with the official documentation in the reference library and verify the exact cloud, region, privileges, and versions you use.

Open the official reference library

Editorial edition: 5 October 2026. The local reference lab is executed locally; this course does not claim a live Databricks deployment.