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
Adam Hernandez
Adam Hernandez
Additional reponses....
1. Reading Orders - Understood, adding them back in. Public reading orders will have endpoints matching the collections pattern:
GET /api/v2/reading-orders/{id}/ Reading order detail (public only)
GET /api/v2/reading-orders/{id}/items/ Items in a reading order (ordered by sequence_number)
Fields (Reading Order): id, name, description, collector (id + username), public (boolean), item_count
Fields (Reading Order Item): id, issue (id + series name + number + descriptor), story (id + title, if present), sequence_number, was_read (boolean)
No list endpoint, same as collections. You need the ID to access it.
2. Collections List Endpoint Removed - Makes sense. "Public" means "viewable with the link," not "discoverable by browsing." The list endpoint is removed. Only the detail and items endpoints remain, and you need the collection ID to access them. Same applies to reading orders.
3. Collection Field Visibility - Good point. Each collection configures which item fields are active via the _used booleans (condition_used, acquisition_date_used, price_paid_used, etc.). I'll add these to the Collection detail response so consumers know which CollectionItem fields will actually have data. Something like:
active_fields: { condition: true, acquisition_date: false, price_paid: true, ... }
That way a consumer can tell whether a null grade means "not graded" or "this collection doesn't track grades."
4. API URL - My assumption is that collections would be served from www.comics.org/api/v2/ alongside everything else, since it's all one Django project and one database. The MYCOMICS flag check in the viewset handles deployments where mycomics isn't enabled (returns 404). But if there's a reason to serve collection endpoints from my.comics.org/api/v2/ instead, happy to structure it that way. What's your preference?
Adam
Jochen G.
> as the existing api run on https://www.comics.org/api/...
my.*, to separate the database from the collection functionality.
I think we want to do the same separation for the API, but that can be seen.
Jochen
Jochen G.
the data in the public dump), my reflects individual data (is not in the
public dump). Reading orders for example are not approved, it is user
data, not GCD data. This distinction should be clear to the API user.
Jochen
Jochen G.
> orders will have endpoints matching the collections pattern:
>
> GET /api/v2/reading-orders/{id}/ Reading order detail (public only)
> GET /api/v2/reading-orders/{id}/items/ Items in a reading order
> (ordered by sequence_number)
>
> Fields (Reading Order): id, name, description, collector (id +
> username), public (boolean), item_count
>
> Fields (Reading Order Item): id, issue (id + series name + number +
> descriptor), story (id + title, if present), sequence_number, was_read
> (boolean)
>
> No list endpoint, same as collections. You need the ID to access it.
potentially searchable. Not done so far. We could add an endpoint, or do
it later once they are searchable.
> 4. API URL - My assumption is that collections would be served from
> www.comics.org/api/v2/ alongside everything else, since it's all one
> Django project and one database. The MYCOMICS flag check in the viewset
> handles deployments where mycomics isn't enabled (returns 404). But if
> there's a reason to serve collection endpoints from my.comics.org/api/
> v2/ instead, happy to structure it that way. What's your preference?
Jochen