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?

[mvdan]

@theckman there are a lot off open issues which require a decision, and most of them don't have assignees. It also doesn't seem to me like this issue is urgent, compared to the other work wrapping up for 1.15.

Having said that, if you look at https://dev.golang.org/owners, you'll see the owners for x/website.

[rsc]

This is a real endpoint that we have repeatedly told people about. It's definitely (past) time for it to be documented. Let's do that.

[dmitshur]

@rsc Given it's already documented at https://pkg.go.dev/golang.org/x/website/internal/dl, I understand this issue is about documenting it elsewhere as well. I've suggested one possibility of making a new page on golang.org (see the last paragraph of #34864 (comment)). Another place could be a new API wiki page. Would either one of those would work, or do you have more thoughts on those two options?

Should we describe the availability of the API, or is it sufficiently implicit that it's the same as that of the golang.org website, given the API endpoint shares the same domain name?

[mvdan]

I vote for documenting it under golang.org, not the wiki, as the latter isn't code reviewed.

Should we describe the availability of the API, or is it sufficiently implicit that it's the same as that of the golang.org website, given the API endpoint shares the same domain name?

I'm not sure what you mean here, but I do think having a full HTTPS link would be useful. Clicking and seeing the data in your browser within a second is a good way to get a feel for how the API works.

[andybons]

I'm not sure what you mean here, but I do think having a full HTTPS link would be useful. Clicking and seeing the data in your browser within a second is a good way to get a feel for how the API works.

I think he meant what users should expect from an uptime perspective.

I don’t think this is necessary beyond maybe setting expectations that it’s supported on a best-effort basis with no guarantees.

[gopherbot]

Change https://golang.org/cl/290231 mentions this issue: internal/dl: document JSON API

[mvdan]

@andybons of course - I'm not sure what I was thinking :)

[gopherbot]

Change https://go.dev/cl/401094 mentions this issue: internal/dl: use go.dev domain in documentation