[philorien]

Closes #443

Description

/series/, /series/{id}/ and /publisher/{id}/series_list/ now return an image URL.

• If a series ever has its own image, that is used.
• Otherwise it falls back to the cover of the series' first issue (ordered by cover_date, store_date, number, id).
• null if there is no cover.

Series has no image field today, so for now every value comes from the fallback. The precedence check is there so a dedicated image can be added later without changing the API.

How

• SeriesImageMixin in api/v1_0/serializers/series.py adds a read-only image field to SeriesListSerializer and SeriesSerializer (so SeriesReadSerializer inherits it). Because it is a SerializerMethodField, the write path is unaffected.
• api/views.py adds a first_issue_image subquery, annotated on the series list, series retrieve and publisher series_list querysets, so there is no per-row query. If the annotation is missing, the serializer falls back to Series.first_issue_cover().
• ModelLabel.ISSUE is added to the series cache_detail_dependent_labels, so a cached detail response does not keep a stale cover after an issue changes. The list view already depended on it.

Tests

Added to tests/comicsdb/test_api_series.py: null cases, detail and list fallback, publisher series list, no per-row queries, dedicated image precedence, and the unannotated serializer path.

I could not run the test suite locally (no Postgres available), so CI is the first real run. ruff check and ruff format --check pass. The query-count test is a relative comparison and may need adjusting.

Checklist

• Tests pass locally (pytest). Not run, no Postgres available to me; relying on CI.
• Linted (ruff check and ruff format --check)
• No user-facing strings changed, so no translation updates needed
• No model changes, so no migrations

[bpepple]

Thanks for putting this together, and for your interest in improving the API. I'm not inclined to merge this at this time, for a few reasons:

1. Series don't really have images. The series image was left out of the API on purpose when it was designed. Covers belong to individual issues, not to the series as a whole. The API also wasn't designed with mobile apps in mind, where showing a cover alongside a series would be more useful.

2. Performance. The series list endpoint is our second most used endpoint. I'd rather not make it any heavier than it already is, because that directly affects server performance.

3. Bandwidth and cost. For the last few months the server has gone over its daily bandwidth allowance by roughly 300–400 GiB. Our budget comes entirely from community donations, so I'd rather not add anything that pushes bandwidth usage up further.

If we plan a v2 of the API, we can look at including the series image then, since it could be designed with that kind of use in mind from the start.

I appreciate the effort here, and I'm sorry this one doesn't fit right now.

P.S. I noticed you're based in Columbus, Ohio. It's nice to see a contributor from here!

[philorien]

@bpepple Thanks for the thorough explanation, that all makes sense, especially the bandwidth situation. I'll close this out. If a v2 gets planned, I'd be glad to help with the series image design. And good to meet a fellow Columbus-area dev.