Versioning of REST API?

[Richard]

Hi Team,

With Copilot's help, I think I can finally get around to implementing
the REST API I've discussed for my.comics.org collections and
collection items. That way I won't need to go through the trouble of
trying to scrape HTML output, I can get direct data access for what I
want.

Looking at master branch, the existing REST API seems rooted under
/api/<endpoint> whereas I was expecting something like
/api/v1/<endpoint>.

Have we discussed versioning of the API?

Thanks,
-- 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>

[Jochen G.]

Nice.

Have only glanced at versioning.

I figure we add versioning once we actually change the API, or go out of
the experimental stage.

But if you can look at how this easily can be done, we can move to it.

Jochen

Am 09.12.25 um 04:40 schrieb Richard:

[Richard]

In article <2c4c0197-1246-4e04...@garcke.de> you write:
>I figure we add versioning once we actually change the API, or go out of
>the experimental stage.
>
>But if you can look at how this easily can be done, we can move to it.

I think it's pretty common to have v1 be endpoints under "/api/..." and
when you introduce an incompatible version change you just put them under
"/api/v2/...".

At the point where versioning is introduced it might make sense to put
in redirects for /api/... to /api/v1/... but then you are imposing new
requirements on clients to pay attention to redirects (which they
should have been doing anyway, but might not have expected).

I never did quite understand how the code handles my.comics.org
differently from comics.org.

Should the collection endpoints only be available on my.comics.org or
should you be able to query collections and their contents from
comics.org/api?

It seems that currently the api endpoints are served identically from
both hosts.

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

[Jochen G.]

Am 15.12.25 um 17:30 schrieb Richard:

> I never did quite understand how the code handles my.comics.org
> differently from comics.org.
>
> Should the collection endpoints only be available on my.comics.org or
> should you be able to query collections and their contents from
> comics.org/api?

The collection functionality should only be under my.comics.org. The
data is accessible under both my and www, where the display is slightly
different.

But I don't think that we would give different data via API ?

> It seems that currently the api endpoints are served identically from
> both hosts.

For an issue, but not for all it seems, e.g. this doesn't work:
https://my.comics.org/api/series/name/Batman/issue/12/

Haven't thought about that so far. I think the data should come www, and
only the collection info should come from my, i.e. keep the API separate.

Jochen