{"course":{"slug":"python-for-ai","title":"Python, from Zero, for AI","url":"https://addaly.com/learn/python-for-ai","level":"beginner","track":"build"},"lesson":{"slug":"an-endpoint-with-fastapi","title":"An HTTP endpoint with FastAPI: your function, callable by any program","url":"https://addaly.com/learn/python-for-ai/an-endpoint-with-fastapi","position":87,"of":89,"minutes":9,"answer":"A FastAPI route is a function with a pydantic model as its argument; the framework parses and validates the request body, returns 422 with the field named when it fails.","keyIdea":"A FastAPI route is a function with a pydantic model as its argument; the framework parses and validates the request body, returns 422 with the field named when it fails, and generates the documentation page at /docs from the same declarations."},"body":{"format":"markdown","text":"## Why an endpoint\n\nA Gradio page is for a person. When another program needs your function (a website's backend, a phone app, a colleague's script, a scheduled job on another machine) it needs an HTTP endpoint: a URL that accepts JSON and returns JSON. Module 6 taught you to *call* such endpoints. This is the other side.\n\nFastAPI (free) is the framework that fits what you know, because its request and response models are pydantic: module 6's validation, now at the door of your own service.\n\n## The smallest service\n\n```python\n# app.py\nfrom fastapi import FastAPI\nfrom pydantic import BaseModel, Field\n\napp = FastAPI(title=\"Notes assistant\")\n\nclass AskRequest(BaseModel):\n    question: str = Field(min_length=1, max_length=2000)\n    k: int = Field(default=5, ge=1, le=20)\n\nclass AskResponse(BaseModel):\n    answer: str\n    sources: list[str]\n\n@app.post(\"/ask\", response_model=AskResponse)\ndef ask(req: AskRequest) -> AskResponse:\n    answer, hits = answer_from_notes(req.question, req.k)\n    return AskResponse(answer=answer, sources=[c[\"doc\"] for _, c in hits])\n```\n\n```bash\npip install fastapi uvicorn\nuvicorn app:app --reload --port 8000\n```\n\n`uvicorn` is the server; `app:app` means the `app` object in `app.py`; `--reload` restarts on file changes during development. Now:\n\n```bash\ncurl -X POST http://127.0.0.1:8000/ask \\\n     -H \"content-type: application/json\" \\\n     -d '{\"question\": \"how do I rotate the key?\"}'\n```\n\nreturns JSON. And `http://127.0.0.1:8000/docs` shows an interactive page listing every route with its request and response schema, generated from the pydantic models: a form you can submit from the browser with no `curl`.\n\n## What the decorator does\n\n`@app.post(\"/ask\")` is module 7's decorator: it registers `ask` as the handler for `POST /ask`. The parameter annotation `req: AskRequest` tells FastAPI to read the request body as JSON, validate it against `AskRequest`, and pass the resulting object in. A body that fails validation never reaches your function; the client receives a **422** with a JSON list of errors naming each bad field: the same `ValidationError` from module 6, formatted for the caller. `response_model` validates what you return, so a bug that puts a `None` in `sources` becomes a 500 in your logs rather than malformed JSON in someone else's program.\n\nPath parameters come from the URL, query parameters from `?k=3`:\n\n```python\n@app.get(\"/notes/{doc_id}\")\ndef get_note(doc_id: str, full: bool = False):\n    ...\n```\n\n`doc_id` is filled from the path; `full` from the query string, converted to `bool`. Type hints are doing real work throughout, which is what the type-checker lesson promised they could.\n\n## Errors you raise\n\n```python\nfrom fastapi import HTTPException\n\nif not hits:\n    raise HTTPException(status_code=404, detail=\"nothing in the notes matches\")\n```\n\nChoose codes as module 6 read them: 400 for a malformed request the validator did not catch, 404 for a thing not found, 429 if you rate-limit, 503 if the model behind you is down. A `RuntimeError` you do not catch becomes a 500 with no detail, correct, since the caller should not see your traceback, but log it with `exc_info=True` so you can.\n\n## Sync, async, and the mistake\n\nFastAPI accepts both `def` and `async def` routes, and the difference is module 6's:\n\n- A plain `def` route runs on a thread from a pool. Blocking calls inside (`requests.post`, sqlite, a local model) are fine; other requests proceed on other threads.\n- An `async def` route runs on the event loop. Only awaitable calls belong inside: `httpx.AsyncClient`, `AsyncOpenAI`. A blocking `requests.post` inside an `async def` stalls the loop, and **every** request waits for it. Ten callers, four seconds each, forty seconds for everyone.\n\nWhen in doubt, write `def`. Switch a route to `async def` only when everything it does is async, and the gain is a server that handles thousands of slow model calls concurrently on one process.\n\n## Startup, and the things that load once\n\nThe index matrix, the embedding model, the provider: load them once, not per request:\n\n```python\nfrom contextlib import asynccontextmanager\n\n@asynccontextmanager\nasync def lifespan(app):\n    app.state.index = load_index(\"index/\")\n    app.state.provider = OllamaProvider()\n    yield\n    # shutdown: close connections here\n\napp = FastAPI(lifespan=lifespan)\n```\n\nModule 7's context manager, wrapping the whole life of the server. Routes reach `app.state.index` through `request.app.state`, or through FastAPI's dependency injection, which is the framework's own composition mechanism.\n\n## Streaming out\n\n```python\nfrom fastapi.responses import StreamingResponse\n\n@app.post(\"/ask/stream\")\ndef ask_stream(req: AskRequest):\n    return StreamingResponse(stream_answer(req.question), media_type=\"text/plain\")\n```\n\nReturn a generator and the client receives it as it is produced: module 6's stream, from the serving side. A browser or a `requests` call with `stream=True` reads it line by line.\n\n## Where the key goes, and who may call\n\nThe service holds the model API key, so the caller never needs one: that is often the point. The service is now the thing to protect. At minimum, require a token in a header and compare it in a dependency; bind to `127.0.0.1` behind a reverse proxy rather than to the world. Deploying, TLS, rate limiting and the rest are the shipping course. The Python you write does not change when it moves.\n\n## Try this now\n\nBuild `/ask` over your notes search, run it, and submit a question from `/docs`. Send a body with `k: 50` and read the 422. Then declare the route `async def` while it still calls a synchronous provider, hit it from a thread pool of ten, and time it, then put `def` back."},"check":{"question":"A FastAPI route is declared `async def summarise(req: Request)` and inside it calls `requests.post(...)` to the model API, which takes four seconds. Under ten simultaneous callers, every request takes about forty seconds. What is the mechanism?","options":[{"text":"FastAPI limits async routes to one request at a time by design, so they must be declared with plain `def` to serve concurrently, which is why the documentation recommends `def` for beginners.","correct":false,"tempting":"Async routes serve many requests at once; that is their purpose. The problem is what this one does inside."},{"text":"uvicorn starts a single worker process, and each worker can hold only one open TCP connection.","correct":false,"tempting":"A worker holds many connections; one process serves thousands of concurrent requests when the code does not block."},{"text":"pydantic validation is synchronous and takes about four seconds per request for a large body.","correct":false,"tempting":"Validation takes microseconds; the four seconds are the model call, which is where the blocking happens."},{"text":"`requests.post` blocks the event-loop thread inside `async def`, so every other request waits; an async client or a plain `def` route would overlap them.","correct":true}]},"prev":{"slug":"a-web-interface-with-gradio","title":"A web interface in twenty lines: Gradio, and what launch() actually starts","url":"https://addaly.com/learn/python-for-ai/a-web-interface-with-gradio"},"next":{"slug":"scheduling-and-idempotent-jobs","title":"Running it every morning: cron, a lock file, and a job that is safe to run twice","url":"https://addaly.com/learn/python-for-ai/scheduling-and-idempotent-jobs"},"authorship":"Founder and series editor: Dr Mustafa Mun. Written by AI models to a written standard. Source and assessment review continues. Academic review invited.","review":{"status":"Draft, open for academic review"},"cite":"Addaly (2026) 'An HTTP endpoint with FastAPI: your function, callable by any program', in Python, from Zero, for AI. Edited by M. Mun. Addaly. Available at: https://addaly.com/learn/python-for-ai/an-endpoint-with-fastapi (Accessed: 21 November 2026).","licence":{"name":"CC BY-NC-SA 4.0","url":"https://creativecommons.org/licenses/by-nc-sa/4.0/"},"reader":{"schema":1,"title":"An HTTP endpoint with FastAPI: your function, callable by any program","courseTitle":"Python, from Zero, for AI","module":{"index":9,"slug":"building-the-thing","title":"Building the thing: a small AI program, end to end"},"answer":null,"keyIdea":"A FastAPI route is a function with a pydantic model as its argument; the framework parses and validates the request body, returns 422 with the field named when it fails, and generates the documentation page at /docs from the same declarations.","hero":{"kind":"plate","image":null,"alt":null,"caption":null},"blocks":[{"t":"h2","id":"why-an-endpoint","runs":[{"text":"Why an endpoint"}]},{"t":"p","runs":[{"text":"A Gradio page is for a person. When another program needs your function (a website’s backend, a phone app, a colleague’s script, a scheduled job on another machine) it needs an HTTP endpoint: a URL that accepts JSON and returns JSON. Module 6 taught you to "},{"text":"call","i":true},{"text":" such endpoints. This is the other side."}]},{"t":"p","runs":[{"text":"FastAPI (free) is the framework that fits what you know, because its request and response models are pydantic: module 6’s validation, now at the door of your own service."}]},{"t":"h2","id":"the-smallest-service","runs":[{"text":"The smallest service"}]},{"t":"code","lang":"python","label":"Python","text":"# app.py\nfrom fastapi import FastAPI\nfrom pydantic import BaseModel, Field\n\napp = FastAPI(title=\"Notes assistant\")\n\nclass AskRequest(BaseModel):\n    question: str = Field(min_length=1, max_length=2000)\n    k: int = Field(default=5, ge=1, le=20)\n\nclass AskResponse(BaseModel):\n    answer: str\n    sources: list[str]\n\n@app.post(\"/ask\", response_model=AskResponse)\ndef ask(req: AskRequest) -> AskResponse:\n    answer, hits = answer_from_notes(req.question, req.k)\n    return AskResponse(answer=answer, sources=[c[\"doc\"] for _, c in hits])"},{"t":"code","lang":"bash","label":"Bash","text":"pip install fastapi uvicorn\nuvicorn app:app --reload --port 8000"},{"t":"p","runs":[{"text":"uvicorn","code":true},{"text":" is the server; "},{"text":"app:app","code":true},{"text":" means the "},{"text":"app","code":true},{"text":" object in "},{"text":"app.py","code":true},{"text":"; "},{"text":"--reload","code":true},{"text":" restarts on file changes during development. Now:"}]},{"t":"code","lang":"bash","label":"Bash","text":"curl -X POST http://127.0.0.1:8000/ask \\\n     -H \"content-type: application/json\" \\\n     -d '{\"question\": \"how do I rotate the key?\"}'"},{"t":"p","runs":[{"text":"returns JSON. And "},{"text":"http://127.0.0.1:8000/docs","code":true},{"text":" shows an interactive page listing every route with its request and response schema, generated from the pydantic models: a form you can submit from the browser with no "},{"text":"curl","code":true},{"text":"."}]},{"t":"h2","id":"what-the-decorator-does","runs":[{"text":"What the decorator does"}]},{"t":"p","runs":[{"text":"@app.post(\"/ask\")","code":true},{"text":" is module 7’s decorator: it registers "},{"text":"ask","code":true},{"text":" as the handler for "},{"text":"POST /ask","code":true},{"text":". The parameter annotation "},{"text":"req: AskRequest","code":true},{"text":" tells FastAPI to read the request body as JSON, validate it against "},{"text":"AskRequest","code":true},{"text":", and pass the resulting object in. A body that fails validation never reaches your function; the client receives a "},{"text":"422","b":true},{"text":" with a JSON list of errors naming each bad field: the same "},{"text":"ValidationError","code":true},{"text":" from module 6, formatted for the caller. "},{"text":"response_model","code":true},{"text":" validates what you return, so a bug that puts a "},{"text":"None","code":true},{"text":" in "},{"text":"sources","code":true},{"text":" becomes a 500 in your logs rather than malformed JSON in someone else’s program."}]},{"t":"p","runs":[{"text":"Path parameters come from the URL, query parameters from "},{"text":"?k=3","code":true},{"text":":"}]},{"t":"code","lang":"python","label":"Python","text":"@app.get(\"/notes/{doc_id}\")\ndef get_note(doc_id: str, full: bool = False):\n    ..."},{"t":"p","runs":[{"text":"doc_id","code":true},{"text":" is filled from the path; "},{"text":"full","code":true},{"text":" from the query string, converted to "},{"text":"bool","code":true},{"text":". Type hints are doing real work throughout, which is what the type-checker lesson promised they could."}]},{"t":"h2","id":"errors-you-raise","runs":[{"text":"Errors you raise"}]},{"t":"code","lang":"python","label":"Python","text":"from fastapi import HTTPException\n\nif not hits:\n    raise HTTPException(status_code=404, detail=\"nothing in the notes matches\")"},{"t":"p","runs":[{"text":"Choose codes as module 6 read them: 400 for a malformed request the validator did not catch, 404 for a thing not found, 429 if you rate-limit, 503 if the model behind you is down. A "},{"text":"RuntimeError","code":true},{"text":" you do not catch becomes a 500 with no detail, correct, since the caller should not see your traceback, but log it with "},{"text":"exc_info=True","code":true},{"text":" so you can."}]},{"t":"h2","id":"sync-async-and-the-mistake","runs":[{"text":"Sync, async, and the mistake"}]},{"t":"p","runs":[{"text":"FastAPI accepts both "},{"text":"def","code":true},{"text":" and "},{"text":"async def","code":true},{"text":" routes, and the difference is module 6’s:"}]},{"t":"ul","items":[[{"text":"A plain "},{"text":"def","code":true},{"text":" route runs on a thread from a pool. Blocking calls inside ("},{"text":"requests.post","code":true},{"text":", sqlite, a local model) are fine; other requests proceed on other threads."}],[{"text":"An "},{"text":"async def","code":true},{"text":" route runs on the event loop. Only awaitable calls belong inside: "},{"text":"httpx.AsyncClient","code":true},{"text":", "},{"text":"AsyncOpenAI","code":true},{"text":". A blocking "},{"text":"requests.post","code":true},{"text":" inside an "},{"text":"async def","code":true},{"text":" stalls the loop, and "},{"text":"every","b":true},{"text":" request waits for it. Ten callers, four seconds each, forty seconds for everyone."}]]},{"t":"p","runs":[{"text":"When in doubt, write "},{"text":"def","code":true},{"text":". Switch a route to "},{"text":"async def","code":true},{"text":" only when everything it does is async, and the gain is a server that handles thousands of slow model calls concurrently on one process."}]},{"t":"h2","id":"startup-and-the-things-that-load-once","runs":[{"text":"Startup, and the things that load once"}]},{"t":"p","runs":[{"text":"The index matrix, the embedding model, the provider: load them once, not per request:"}]},{"t":"code","lang":"python","label":"Python","text":"from contextlib import asynccontextmanager\n\n@asynccontextmanager\nasync def lifespan(app):\n    app.state.index = load_index(\"index/\")\n    app.state.provider = OllamaProvider()\n    yield\n    # shutdown: close connections here\n\napp = FastAPI(lifespan=lifespan)"},{"t":"p","runs":[{"text":"Module 7’s context manager, wrapping the whole life of the server. Routes reach "},{"text":"app.state.index","code":true},{"text":" through "},{"text":"request.app.state","code":true},{"text":", or through FastAPI’s dependency injection, which is the framework’s own composition mechanism."}]},{"t":"h2","id":"streaming-out","runs":[{"text":"Streaming out"}]},{"t":"code","lang":"python","label":"Python","text":"from fastapi.responses import StreamingResponse\n\n@app.post(\"/ask/stream\")\ndef ask_stream(req: AskRequest):\n    return StreamingResponse(stream_answer(req.question), media_type=\"text/plain\")"},{"t":"p","runs":[{"text":"Return a generator and the client receives it as it is produced: module 6’s stream, from the serving side. A browser or a "},{"text":"requests","code":true},{"text":" call with "},{"text":"stream=True","code":true},{"text":" reads it line by line."}]},{"t":"h2","id":"where-the-key-goes-and-who-may-call","runs":[{"text":"Where the key goes, and who may call"}]},{"t":"p","runs":[{"text":"The service holds the model API key, so the caller never needs one: that is often the point. The service is now the thing to protect. At minimum, require a token in a header and compare it in a dependency; bind to "},{"text":"127.0.0.1","code":true},{"text":" behind a reverse proxy rather than to the world. Deploying, TLS, rate limiting and the rest are the shipping course. The Python you write does not change when it moves."}]},{"t":"h2","id":"try-this-now","runs":[{"text":"Try this now"}],"role":"try"},{"t":"p","runs":[{"text":"Build "},{"text":"/ask","code":true},{"text":" over your notes search, run it, and submit a question from "},{"text":"/docs","code":true},{"text":". Send a body with "},{"text":"k: 50","code":true},{"text":" and read the 422. Then declare the route "},{"text":"async def","code":true},{"text":" while it still calls a synchronous provider, hit it from a thread pool of ten, and time it, then put "},{"text":"def","code":true},{"text":" back."}]}],"check":{"question":[{"text":"A FastAPI route is declared "},{"text":"async def summarise(req: Request)","code":true},{"text":" and inside it calls "},{"text":"requests.post(...)","code":true},{"text":" to the model API, which takes four seconds. Under ten simultaneous callers, every request takes about forty seconds. What is the mechanism?"}],"options":[{"text":[{"text":"FastAPI limits async routes to one request at a time by design, so they must be declared with plain "},{"text":"def","code":true},{"text":" to serve concurrently, which is why the documentation recommends "},{"text":"def","code":true},{"text":" for beginners."}],"correct":false,"tempting":[{"text":"Async routes serve many requests at once; that is their purpose. The problem is what this one does inside."}]},{"text":[{"text":"uvicorn starts a single worker process, and each worker can hold only one open TCP connection."}],"correct":false,"tempting":[{"text":"A worker holds many connections; one process serves thousands of concurrent requests when the code does not block."}]},{"text":[{"text":"pydantic validation is synchronous and takes about four seconds per request for a large body."}],"correct":false,"tempting":[{"text":"Validation takes microseconds; the four seconds are the model call, which is where the blocking happens."}]},{"text":[{"text":"requests.post","code":true},{"text":" blocks the event-loop thread inside "},{"text":"async def","code":true},{"text":", so every other request waits; an async client or a plain "},{"text":"def","code":true},{"text":" route would overlap them."}],"correct":true,"tempting":null}],"order":[2,0,1,3],"why":null},"prev":{"slug":"a-web-interface-with-gradio","title":"A web interface in twenty lines: Gradio, and what launch() actually starts","minutes":8},"next":{"slug":"scheduling-and-idempotent-jobs","title":"Running it every morning: cron, a lock file, and a job that is safe to run twice","minutes":9}}}