Add a paginated GET /images listing endpoint — feature ticket · 10xDebuggable

Image Service — Stream, Validate, and Thumbnail Uploads with FastAPI

enhancementintermediateP2app/main.py, app/schemas.pyLevel 2 · Implement a feature15 XP45–90 minutes

Add a paginated GET /images listing endpoint

Nobody has started this yet — be first.

Business impact

Today there is no way to ask the API "what images exist?" -- a client (or an internal admin tool, or a support engineer trying to help a confused user) can only look up a single image if it already knows the id. Any dashboard, gallery UI, or "show me my uploads" feature that a product team wants to build on top of this service is blocked until this endpoint exists. This is the single most common gap reported by teams integrating with a single-resource-lookup-only API.

Problem

GET /images exists as a stub only. It accepts limit/offset query parameters and returns the right shape (ImageListResponse), but the handler ignores the database entirely and always returns {"items": [], "total": 0, "limit": ..., "offset": ...}, no matter how many images have actually been uploaded. This is enough for the route to exist, be documented in /docs, and compile -- but it is not a real implementation.

Current behavior

GET /images?limit=&offset= always responds with an empty items array and total: 0, regardless of how many images are actually stored in the database.

Expected behavior

GET /images?limit=&offset= should return the images actually stored in the database, most-recently-created first, with real pagination: items holds up to limit images starting after offset items, ordered by created_at descending; total reflects the full matching count in the database, not just the page size, so a client can compute how many pages exist; limit and offset are echoed back as received (already correct in the stub). Each item should carry the same summary information GET /images/{id} exposes for a single image -- id, status, original_url, format, width, height, file_size, created_at -- via the already-defined ImageSummary schema.

Steps to reproduce

uvicorn app.main:app --reload

upload two or three images via POST /images first, then:

curl -s "http://localhost:8000/images?limit=1&offset=1"

-> {"items": [], "total": 0, "limit": 1, "offset": 1} -- even though images exist

Why this matters

models.ImageRecord (app/models.py) already has everything needed: created_at for ordering, and all the summary fields. This is a pure database-querying exercise using the db: Session already injected into the route via Depends(get_db) -- no new storage or processing logic is required.

Suggested approach

Look at list_images in app/main.py -- it's the GET /images route, currently a two-line stub. You'll want to query db.query(models.ImageRecord) (or the SQLAlchemy 2.0 select() style, if you prefer -- get_image_metadata right below shows the db.get(...) style used elsewhere in this file, though a query for all rows needs something different from a single-row get), order by created_at descending, get a total count of matching rows before applying limit/offset, then apply .offset(offset).limit(limit) for the page itself. Build ImageSummary objects from each row the same way get_image_metadata builds an ImageMetadataResponse from one.

Acceptance criteria

GET /images with no query params returns up to 20 most-recent images (default limit=20) and the correct total.
GET /images?limit=1&offset=1 returns exactly 1 item (the second-most-recent image) and total still reflects the full count, not the page size.
An empty database returns {"items": [], "total": 0, ...} (the stub already does this correctly -- don't regress it).
practicetickets/test_ticket03_list_images_pagination.py passes.

Verification

pytest practicetickets/test_ticket03_list_images_pagination.py -v

Hints (0/2)

Try it without hints first — the reading is the exercise.

Working on this ticket

Work on a branch named for the ticket — that's what you'll submit.

Branch off your fork

$git checkout -b feat/list-images-pagination

Fix it and commit

Meet every acceptance criterion, and add a test that would have caught this.

Push the branch

$git push -u origin feat/list-images-pagination

Submit it below

Paste your fork URL and the branch name, with a short write-up of the root cause.

Submit your fix

Questions

Stuck on something?

Ask about anything unclear in the ticket — the maintainer and anyone who has solved it can answer. Please don't post full solutions.

No questions yet. If something in this ticket reads ambiguously, you are probably not the only one — ask.

The project

Image Service — Stream, Validate, and Thumbnail Uploads with FastAPI

A FastAPI file-upload and thumbnail-processing API where the central engineering problem is not the upload itself but everything that has to happen correctly once the HTTP response has already been sent -- background image processing, a three-state lifecycle, and the precise status codes a polling client depends on.

Fork on GitHub

Download

Setup

Image Service — Stream, Validate, and Thumbnail Uploads with FastAPI

git clone <your-fork>
cd fastapi/image_service
docker compose up --build   # -> http://localhost:8000/docs

That's the primary path -- bind-mounts and and runs , with a named volume persisting (uploads + the SQLite file) across restarts. A production-style build (multi-stage , non-root user, no bind mount) is available via .

docker-compose.yml

./app

./tests

uvicorn --reload

/app/data

Dockerfile.prod

docker compose -f docker-compose.prod.yml up --build -d

cd fastapi/image_service
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
cp .env.example .env   # optional, defaults work out of the box
uvicorn app.main:app --reload   # -> http://127.0.0.1:8000/docs

pytest practicetickets/test_ticket01_upload_size_boundary.py -v   # a single ticket
./practicetickets/run_tickets.sh                                    # all 7, clean pass/fail summary