fastapi-rbac-search

A small, fully typed FastAPI service: keyword search over a document repository that only returns the documents the caller's role is allowed to see.

It is deliberately compact — a sample of how I structure a typed Python API, not a product.

What it shows

• Generic response envelopes — Response[S, D] and ListResponse[S, D] (app/models.py) give every endpoint the same { "status": ..., "data": ... } shape while keeping the payload type checked.
• Literal domain types — Role and Department are closed sets, so an unknown role is a 422 from FastAPI's request validation rather than a branch in the handler.
• Pydantic v2 models with a camelCase alias generator for the wire format, and a TypeAdapter that loads and validates the whole docs.json in one call.
• Tooling: uv for environments, ruff for lint + format, ty for type checking, pytest for the tests — all wired into CI.

Run it

uv run uvicorn app.main:app --reload
# docs: http://127.0.0.1:8000/docs

curl 'http://127.0.0.1:8000/documents?q=rollback&role=ops'
# {"status":"ok","data":["doc-001"]}

curl -i 'http://127.0.0.1:8000/documents?q=rollback&role=hr'
# 404 — "hr" is not on doc-001's permission list

Develop

uv sync
uv run ruff format --check && uv run ruff check
uv run ty check
uv run pytest

Layout

app/
  main.py        FastAPI app + router wiring
  routes.py      GET /documents — the role-filtered search
  models.py      response envelopes, Literal domain types, the Document model
  documents.py   loads + validates app/docs.json into a list[Document]
  docs.json      the sample repository (12 documents)
tests/           end-to-end tests against the app via TestClient