API v2 and Collections info - Need Jochen's Input on a requested scope change
Adam Hernandez
GET /api/v2/collections/ List public collections GET /api/v2/collections/{id}/ Collection detail (public only) GET /api/v2/collections/{id}/items/ Items in a collection
Fields (Collection): id, name, description, collector (id + username), public (boolean), keywords, item_count
Fields (Collection Item): id, issue (id + series name + number + descriptor), grade (code + name, from ConditionGrade), own (boolean: owned vs wanted), was_read (boolean), for_sale (boolean), signed (boolean), is_digital (boolean), rating (1-5 scale), acquisition_date, sell_date, location (id + name), purchase_location (id + name), price_paid (amount + currency code), market_value (amount + currency code), sell_price (amount + currency code), notes, keywords
Filters (Collection list): collector (user id), name (icontains)
Filters (Collection Items): series, publisher (via issue__series__publisher), own, was_read, signed, is_digital, for_sale, rating (range), price_paid (range), market_value (range), sell_price (range), publication_date (range, via issue__key_date)
Notes:
- CollectionItem uses a ManyToMany relationship to Collection, meaning a single item can belong to multiple collections. The /collections/{id}/items/ endpoint returns items where the specified collection is in the item's collection set.
- The existing CollectionItemFilter in apps/mycomics/models.py already implements most of these filters using django-filter. The v2 filter set can build directly on that work.
- Collection and CollectionItem do not currently have created or modified timestamp fields. If those fields are added to the models in the future, they should be exposed as response fields and range filters consistent with every other v2 endpoint.
------------------
Subscriptions
GET /api/v2/collections/{id}/subscriptions/ Series subscribed to a collection
Fields: id, series (id + name + year_began), last_pulled (datetime)
Subscriptions automatically pull new issues into a collection as they get added to the GCD database. Exposing them through the API lets consumers see which series a collection is tracking without scraping the web UI.
-----------------
Permissions
Only collections and reading orders marked public = True are visible through the API. Private resources return 404 with no information leakage about their existence.
- Anonymous and authenticated users can query any public collection or reading order by ID
- Authenticated users seeing their own private collections is a future enhancement, not required for the initial implementation
Implementation Notes
The MYCOMICS setting in settings.py defaults to False. All collection and reading order endpoints should check this flag. If MYCOMICS is disabled on a given deployment, these endpoints return 404 with a clear message rather than raising an unhandled error.
What is not included
- Write endpoints for collection management (add/remove items, create/delete collections)
- Private collection access for authenticated collection owners
- Collection statistics (total value, completion percentages, etc.)
- Import/export through the API
- Condition grade scales as a standalone reference endpoint
Richard
>Only collections and reading orders marked public = True are visible
>through the API.
them.
Personally, the endpoints you gave for collections and collection
items are sufficient for my primitive "want list" app.
Reading orders are a relatively new feature and I'm guessing it might
evolve further before we have a need to expose it through the API.
-- Richard
--
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
The Terminals Wiki <http://terminals-wiki.org>
The Computer Graphics Museum <http://computergraphicsmuseum.org>
Legalize Adulthood! (my blog) <http://legalizeadulthood.wordpress.com>
Adam Hernandez
Adam Hernandez
Clean up version, removed reading order referenced...
GET /api/v2/collections/ List public collections GET /api/v2/collections/{id}/ Collection detail (public only) GET /api/v2/collections/{id}/items/ Items in a collection
Fields (Collection): id, name, description, collector (id + username), public (boolean), keywords, item_count
Fields (Collection Item): id, issue (id + series name + number + descriptor), grade (code + name, from ConditionGrade), own (boolean: owned vs wanted), was_read (boolean), for_sale (boolean), signed (boolean), is_digital (boolean), rating (1-5 scale), acquisition_date, sell_date, location (id + name), purchase_location (id + name), price_paid (amount + currency code), market_value (amount + currency code), sell_price (amount + currency code), notes, keywords
Filters (Collection list): collector (user id), name (icontains)
Filters (Collection Items): series, publisher (via issue__series__publisher), own, was_read, signed, is_digital, for_sale, rating (range), price_paid (range), market_value (range), sell_price (range), publication_date (range, via issue__key_date)
Notes:
- CollectionItem uses a ManyToMany relationship to Collection, meaning a single item can belong to multiple collections. The /collections/{id}/items/ endpoint returns items where the specified collection is in the item's collection set.
- The existing CollectionItemFilter in apps/mycomics/models.py already implements most of these filters using django-filter. The v2 filter set can build directly on that work.
- Collection and CollectionItem do not currently have created or modified timestamp fields. If those fields are added to the models in the future, they should be exposed as response fields and range filters consistent with every other v2 endpoint.
------------------
Subscriptions
GET /api/v2/collections/{id}/subscriptions/ Series subscribed to a collection
Fields: id, series (id + name + year_began), last_pulled (datetime)
Subscriptions automatically pull new issues into a collection as they get added to the GCD database. Exposing them through the API lets consumers see which series a collection is tracking without scraping the web UI.
-----------------
Permissions
Only collections marked public = True are visible through the API. Private resources return 404 with no information leakage about their existence.
- Anonymous and authenticated users can query any public collection by ID
- Authenticated users seeing their own private collections is a future enhancement, not required for the initial implementation
Implementation Notes
The MYCOMICS setting in settings.py defaults to False. All collection endpoints should check this flag. If MYCOMICS is disabled on a given deployment, these endpoints return 404 with a clear message rather than raising an unhandled error.
What is not included
- Write endpoints for collection management (add/remove items, create/delete collections)
- Private collection access for authenticated collection owners
- Collection statistics (total value, completion percentages, etc.)
- Import/export through the API
- Condition grade scales as a standalone reference endpoint
Jochen G.
are announced as open and searchable.
Public collections should not be searchable, at least not without
further say so from our users. Public means someone I give the link can
have a look. Public does not mean anyone should be able to find it, at
least it is the way they were introduced and communicated.
So
GET /api/v2/collections/{id}/ Collection detail (public only)
GET /api/v2/collections/{id}/items/ Items in a collection
now), but I am not against it. Making authentication work should be a
straightforward next step.
Am 20.04.26 um 22:56 schrieb Adam Hernandez:
>
> I was going to include a reading order endpoint, but removed it. I must
> have missed a reference. I'll clean up the doc, let me know if you have
> any other concerns.
>
> Adam
>
> On Sunday, April 19, 2026 at 6:44:13 PM UTC-7 lega...@xmission.com wrote:
>
> In article <fcce1da3-3918-450e...@googlegroups.com> you write:
> >Only collections and reading orders marked public = True are visible
> >through the API.
>
> You mention reading orders here, but there isn't any endpoint for
> them.
>
> Personally, the endpoints you gave for collections and collection
> items are sufficient for my primitive "want list" app.
>
> Reading orders are a relatively new feature and I'm guessing it might
> evolve further before we have a need to expose it through the API.
>
> -- Richard
>
> --
> "The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-
> The Terminals Wiki <http://terminals-wiki.org <http://terminals-
> The Computer Graphics Museum <http://computergraphicsmuseum.org
> <http://computergraphicsmuseum.org>>
> Legalize Adulthood! (my blog) <http://
> legalizeadulthood.wordpress.com>>
>
> --
> You received this message because you are subscribed to the Google
> Groups "gcd-tech" group.
> To unsubscribe from this group and stop receiving emails from it, send
> an email to gcd-tech+u...@googlegroups.com <mailto:gcd-
> tech+uns...@googlegroups.com>.
> To view this discussion visit https://groups.google.com/d/msgid/gcd-
> tech/ad529454-f5ea-44bd-b27b-711f71b526dan%40googlegroups.com <https://
> groups.google.com/d/msgid/gcd-tech/ad529454-f5ea-44bd-
> b27b-711f71b526dan%40googlegroups.com?utm_medium=email&utm_source=footer>.
Richard
>Public collections should not be searchable, at least not without
Yeah, I wasn't expecting my collections to be found by search, but if
someone has the URL to my public collection they can browse the
contents of the collection.
--
"The Direct3D Graphics Pipeline" free book <http://tinyurl.com/d3d-pipeline>
Jochen G.
> Clean up version, removed reading order referenced...
>
> GET /api/v2/collections/ List public collections GET /api/v2/
> collections/{id}/ Collection detail (public only) GET /api/v2/
> collections/{id}/items/ Items in a collection
>
> public (boolean), keywords, item_count
many CollectionItem data are optional per collection. This info should
be accessible, I think ?
> *Fields (Collection Item):* id, issue (id + series name + number +
> owned vs wanted), was_read (boolean), for_sale (boolean), signed
> (boolean), is_digital (boolean), rating (1-5 scale), acquisition_date,
> sell_date, location (id + name), purchase_location (id + name),
> price_paid (amount + currency code), market_value (amount + currency
> code), sell_price (amount + currency code), notes, keywords
>
>
> The MYCOMICS setting in settings.py defaults to False. All collection
> endpoints should check this flag. If MYCOMICS is disabled on a given
> deployment, these endpoints return 404 with a clear message rather than
> raising an unhandled error.
Jochen