API v2 - PRD

[Adam Hernandez]

So being an old engineer that turned into a product manager for the last 15 years, I felt the need to create a PRD for the API rewrite I'd like to do (and got told no objections). So attached is a link to a google doc of the PRD that I have been working on as a proposal for the last few weeks. It was originally a word docx, so to make it easier for everybody to review I put everything into a google doc yesterday. It's open for comments by anyone in the group. I'll leave it open for one week and respond to all comments as they come in. See link below...

https://docs.google.com/document/d/1Ye21s8bJM4FuU35fHqOTEbWYF-3Cd76MvqijcWFz8mE/edit?usp=sharing

Adam

[Kyle Jerviss]

Looks good to me. I'll even volunteer to help with testing.

A while back, I had considered simply adding the raw database fields to
the existing API (without taking away any of the current composite
fields), but other things came up and I never got around to setting up a
dev environment.

Even with rate limits, this will probably become some people's preferred
method of access, which will increase load on the servers. Could we
think about monetizing higher-rate API access as a way to offset the
cost of that load? I'd be willing to pay a few bucks a month for
improved access in between MySQL dumps.

> --
> 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.
> To view this discussion visit
> https://groups.google.com/d/msgid/gcd-tech/38367df2-7005-4711-9591-75262d115f97n%40googlegroups.com
> [1].
>
>
> Links:
> ------
> [1]
> https://groups.google.com/d/msgid/gcd-tech/38367df2-7005-4711-9591-75262d115f97n%40googlegroups.com?utm_medium=email&utm_source=footer

[Adam Hernandez]

I totally agree on the monetization of higher-rate API access, it should help offset the costs. I would leave the existing rates for now, and then we could look at monetization later. The way that I figure it the majority of users will be unlikely to use more than 2000/day it'll probably be around a 90/10 split. Thanks for reviewing the PRD, if you have any question later just let me know. 

Adam

[Jochen G.]

It likely will be a couple of days before I can have a closer look.

On quick glance I saw a covers endpoint. That would give bulk access to
covers, which we don't do. Right now the URL is on the issue point,
replicating how a webpage would behave.

Am 14.04.26 um 12:50 schrieb Adam Hernandez:

> <https://docs.google.com/document/
> d/1Ye21s8bJM4FuU35fHqOTEbWYF-3Cd76MvqijcWFz8mE/edit?usp=sharing>

>
> Adam
>
> --
> 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/38367df2-7005-4711-9591-75262d115f97n%40googlegroups.com <https://
> groups.google.com/d/msgid/gcd-
> tech/38367df2-7005-4711-9591-75262d115f97n%40googlegroups.com?
> utm_medium=email&utm_source=footer>.

[Adam Hernandez]

Understood on the covers. I pulled that end point from the scope as well as the cover_url on the issues end point. I also removed and reference to covers in the PRD. Thanks for the guidance. 

Adam

[Richard]

I responded with comments on the google doc.

Overall looks great!

-- 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]

Richard, I responded to all your comments in the doc take a look and let me know if you have anything else. 

Thanks, 

Adam

[Adam Hernandez]

All, I've updated the prd based on user feedback to include conditional requests, a modified filter, and an optional recommendation for use of fail2ban to help with abuse prevention. Take a look and let me now what you think. 

Adam

[Jochen G.]

On the issue end point the cover_url is fine, it is essentially the same
as parsing the website. For simplicity only the first cover is exposed
currently though.

Accessing covers on their own would be different.

Am 14.04.26 um 20:25 schrieb Adam Hernandez:

> Understood on the covers. I pulled that end point from the scope as well
> as the cover_url on the issues end point. I also removed and reference
> to covers in the PRD. Thanks for the guidance.
> Adam
>
> On Tuesday, April 14, 2026 at 8:01:10 PM UTC-7 Jochen G. wrote:
>
> It likely will be a couple of days before I can have a closer look.
>
> On quick glance I saw a covers endpoint. That would give bulk access to
> covers, which we don't do. Right now the URL is on the issue point,
> replicating how a webpage would behave.
>
> Am 14.04.26 um 12:50 schrieb Adam Hernandez:
> > So being an old engineer that turned into a product manager for
> the last
> > 15 years, I felt the need to create a PRD for the API rewrite I'd
> like
> > to do (and got told no objections). So attached is a link to a
> google
> > doc of the PRD that I have been working on as a proposal for the
> last
> > few weeks. It was originally a word docx, so to make it easier for
> > everybody to review I put everything into a google doc yesterday.
> It's
> > open for comments by anyone in the group. I'll leave it open for one
> > week and respond to all comments as they come in. See link below...
> >

> > https://docs.google.com/document/ <https://docs.google.com/
> document/>
> > d/1Ye21s8bJM4FuU35fHqOTEbWYF-3Cd76MvqijcWFz8mE/edit?usp=sharing
> > <https://docs.google.com/document/ <https://docs.google.com/
> document/>

> > d/1Ye21s8bJM4FuU35fHqOTEbWYF-3Cd76MvqijcWFz8mE/edit?usp=sharing>
> >
> > Adam
> >
> > --
> > 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- <https://groups.google.com/d/msgid/gcd->
> > tech/38367df2-7005-4711-9591-75262d115f97n%40googlegroups.com
> <http://40googlegroups.com> <https://
> > groups.google.com/d/msgid/gcd- <http://groups.google.com/d/msgid/
> gcd->
> > tech/38367df2-7005-4711-9591-75262d115f97n%40googlegroups.com
> <http://40googlegroups.com>?
> > utm_medium=email&utm_source=footer>.

>
> --
> 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/5d7336ce-2f90-47c9-b5d5-94c72806f5efn%40googlegroups.com <https://
> groups.google.com/d/msgid/gcd-tech/5d7336ce-2f90-47c9-
> b5d5-94c72806f5efn%40googlegroups.com?utm_medium=email&utm_source=footer>.

[Richard]

In article <c5125cb9-521f-42bc...@googlegroups.com> you write:
>Richard, I responded to all your comments in the doc take a look and let me
>know if you have anything else.

Thanks, added a couple replies and echoed Jochen's comment that
supplying the cover URL for an issue would be acceptable, noting that
it wouldn't supply variant cover URLs. That is fine, I think
querying for variant cover info should be a separate endpoint, e.g.
"give me a list of variant info for this issue id".

--
"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]

Richard, I replied to your comments in the doc, but I also added a section specific to implementing a small ci pipeline. Please reveiw it and let me know what you think. 

Adam