Organize routes and return consistent errors

In this lesson you will organize routes and return consistent errors. Work with the Equipment Rental API in the downloadable lab. The reference is a complete solution with separate lesson checks, so you can inspect the answer, make a deliberate local change and verify its behavior.

Organize the API around resources and stable client behavior. GET /equipment reads equipment; POST /rentals reserves it; POST /rentals/{id}/check-in expresses a state transition. The integrated app delegates transactions to services instead of mixing every database operation into route functions. A larger application can put these groups in APIRouter modules without changing the public paths.

DomainError carries a public code, message and status. A single exception handler turns it into a predictable error envelope. Missing resources produce 404, a capacity conflict produces 409 and a denied action produces 403. FastAPI's request validation has its own 422 format in this reference; document both formats rather than claiming every failure is identical. A database IntegrityError maps to a fixed 409 response without returning SQL or a traceback. A failure contract helps clients decide whether to correct input, authenticate or wait. Internal diagnostic detail belongs in controlled server evidence, never in a raw HTTP error body.

Worked source: equipment/errors.py, DomainError.

Use the API contract review sheet to write the rental read contract. In api.py locate the handler and rental_read route. The lesson04 check authenticates a synthetic owner, requests a missing UUID and verifies the exact 404 envelope. Compare it with the invalid integer path example from lesson 1.

class DomainError(Exception):
    def __init__(self, code, message, status=409):
        super().__init__(message)
        self.code, self.message, self.status = code, message, status

python run_checks.py -k lesson04