Module 1 of 9 · Lesson 1 of 26

Build your first synchronous HTTP endpoint

Work through build your first synchronous HTTP endpoint using a runnable reference, a focused regression check and a local extension.

Read in any order. All lessons stay open, including after an unanswered or incorrect check.

In this lesson you will build your first synchronous HTTP endpoint. 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.

An HTTP endpoint connects a method and path to one function. In equipment/hello.py, GET /equipment/7 passes the integer 7 into describe and returns a JSON object. The Python function uses def: FastAPI can run this synchronous route in its worker thread pool. It does not need async syntax to return a dictionary. The path annotation is also an input contract. A non-integer identifier is rejected before the function runs, and POST to a GET-only route produces a method error.

Keep the first example small enough to explain from request to response. The id is taken from the path, while the name and availability are deliberately fixed demonstration data. Nothing is persisted, so this endpoint must not claim to show live stock. Uvicorn serves the application; FastAPI chooses the route, validates its input and serializes its output. An HTTP client sees the status, headers and body, rather than the Python implementation.

Worked source: equipment/hello.py, describe.

Start python -m uvicorn equipment.hello:app --port 8000 from the extracted lab directory. Request /equipment/7, /equipment/not-an-integer and POST /equipment/7. Predict the three statuses, then inspect them. Stop the server before running the lesson check. Its assertions verify 200-style success, 422 validation and 405 method rejection.

pythonCopyable

@app.get("/equipment/{equipment_id}")
def describe(equipment_id: int):
    return {"id": equipment_id, "name": "Tripod", "available": True}

TerminalPython 3.13 virtual environment; Docker running; extracted lab directory

python run_checks.py -k lesson01

Expected result The selected lesson test passes against a new temporary PostgreSQL database; the container is removed afterward.

Keep for reference

Equipment Rental lab and lesson checks

ZIP containing Python source, real Alembic migrations, 26 lesson checks, a dependency lock and text instructions. Extract it before following the local exercise.

Download Equipment Rental lab and lesson checks

Practise locally

Add GET /equipment/{equipment_id}/availability in your own copy. Return the same integer id and a clearly labeled demonstration availability value. Add a TestClient assertion for a valid id and a second assertion for invalid text. Keep the original route working. Save the test output and explain which input is validated before your function runs.

The lesson check verifies the reference behavior. Add your own assertions for your change. Local practice is not uploaded or scored by this learning release.

Pause and reflect

What failure does this lesson prevent, and which assertion in lesson01 would expose it?

Use a concrete input, expected result and limitation from your local work. Saving a reflection does not certify the project.

Optional knowledge check

Why does /equipment/not-an-integer fail before describe runs?

The int path annotation rejects invalid input.

Correct. FastAPI validates the annotated path before calling the endpoint.

The demonstration stock record cannot be found.

Try another answer. This first example has no database lookup; the failure concerns the path contract.

The HTTP client validates the path only after the server returns.

Try another answer. Server-side annotated validation happens before the endpoint runs.

This practice does not assess your project or award a certificate.

Your reading progress

Progress is saved in this browser when storage is available.