Re: Add versions.json endpoint with latest release information

On Fri, Apr 30, 2021 at 1:06 PM Sehrope Sarkuni <sehrope(at)jackdb(dot)com> wrote:
>
> On Fri, Apr 30, 2021 at 5:59 AM Magnus Hagander <magnus(at)hagander(dot)net> wrote:
>>
>> * Why do we care about sorting the keys? Not that it matters much, but
>> it mostly seems a bit silly, but if there is a reasoning behind it
>> there's no problem -- I'd just like to know what the reasoning is.
>
>
> It's sorted to ensure a completely stable HTTP response. It shouldn't matter or be relied upon by any external consumer of the data, but it's mildly convenient to know that the handler response will be byte-for-byte consistent regardless of Python version or if the response is cached. It makes testing a tad easier too as you can rely on an "==" on the raw response text.

Hmm. Testability definitely is a good point.

>> * It reports major version as "13.0", not "13". It's correct for
>> versions prior to 10.
>
>
> Is there an updated set of sample data? I cloned the project and followed the dev setup instructions, but the initial data it loads only goes up to 8.4.

Yeah, the fixtures are in a sad state.

We should really try to get a process to handle that, as it's now
extremely ad-hoc. I've added a script for it and refreshed the
current ones now so if you pull you'll at least get what's right at
this moment, even though it'll rapidly get outdated again. But please
try it and see if it breaks :)

>> * I'm thinking the orignal name "latestminor" is actually better than
>> "minor" -- the previous minor releases still exist after all.
>
> I was back and forth on this as well. I figured the endpoint itself represents the latest for each major version so having it be "minor" made more sense.

Hehe. I had the same pattern of thinking, but came to the other conclusion :)

Jonathan, want to cast a deciding vote?

> A separate endpoint with all historical minor versions could then also have the same structure.

It could, but we don't actually keep track of historical minor
versions anywhere at this point. It might be interesting to do so, but
that's a bigger and separate patch, so let's not get that in the way
of getting this one approved.

>> * Would it make sense to have an actual query parameter like
>> "?current=1" or something that would give you *just* the current
>> version? To avoid having to download all? And maybe also
>> "?supported=1" to get just supported versions? To avoid having to do
>> those filterings client side?
>
>
> My own use case would use the full list though I can see both "current" and "supported" being useful as well.
>
> If we structure the URL to support that in the future I think that's fine. Rather than query parameters could have totally separate end points:
>
> /versions/all.json - Array response with latest of each major version
> /versions/supported.json - Array response with list of supported versions
> /versions/current.json - Object response of only current version
>
> I don't know which of those would play nicer with how the HTTP caching works. The expectation is that these endpoints are going to be hit repeatedly by things like CI platforms so we should get that part right.

It should make no practical difference wrt caching. It's still just 3
URLs -- it would get bad if we supposed a huge mix of combinations,
but we wouldn't.

That said, thinking more about it maybe that's all over engineering
things. Anybody who's going to want a json file back is going to be
able to do the parse/filter step easily. So the only real reason to
separate them would be to reduce bandwidth -- and I can't believe that
a gzipped (transfer encoding) json file with all our versions is going
to be big enough to cause any issues..

--
Magnus Hagander
Me: https://www.hagander.net/
Work: https://www.redpill-linpro.com/