x/website/internal/dl: document /dl/?mode=json API more prominently

[jmhodges]

It would be nice for the JSON mode of golang.org/dl to be documented somewhere (https://golang.org/dl/?mode=json). I wasn't able to find it until after I built a project to recreate the same functionality and someone pointed it out.
Having a JSON API for Go releases is great and I think some folks would build more tools using it if we had it documented.

[agnivade]

There's also an include=all 😉

The docs are there (https://godoc.org/golang.org/x/website/internal/dl) but it's pretty hidden. I agree we should document it somewhere more prominent. Perhaps some place in https://golang.org/dl/ itself.

@andybons @dmitshur

[mvdan]

I agree. Multiple times I've found people using GitHub's releases API to see what Go versions have been released, when using the /dl json document would be far better.

[dmitshur]

If we decide to document this API more prominently, we should be clear about its stability and reliability. Them being documented only in internal packages is a signal they're primarily for our own use and that they can change and that they don't have a public SLO.

By the way, there is yet another primarily-for-internal-use-so-no-stability-guarantees gRPC-based API for determining latest Go releases. A client for it is available in the apipb package. See here for example usage.

If we decide to document these more prominently, perhaps it would make sense to create a new API page on the golang.org website where various APIs, including /dl?mode=json, can be documented. This page can be listed under the Developer Resources section of the Go project page. Then golang.org/dl can include a short sentence with a link to it, rather than providing all the details.

[mvdan]

they can change and that they don't have a public SLO

While I see your point there, it's probably too late for any breaking changes at this point. For example, any backwards-incompatible change would break https://github.com/actions/setup-go, and thus would break practically all GitHub Actions that need Go.

It's true that the API was never announced or publicly documented, but it was made de facto stable the moment that it went live under an easy-to-use golang.org endpoint, in my opinion.

[theckman]

@agnivade @mvdan @dmitshur @andybons this issue is marked as "NeedsDecision", but it doesn't seem like anyone is assigned. Who is tasked with making the decision on this issue?