Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
jmhodges opened this issue Oct 12, 2019 · 8 comments
Open

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

jmhodges opened this issue Oct 12, 2019 · 8 comments

Comments

@jmhodges
Copy link
Contributor

@jmhodges jmhodges commented Oct 12, 2019

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
Copy link
Contributor

@agnivade agnivade commented Oct 13, 2019

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

@agnivade agnivade changed the title doc: JSON API for golang.org/dl x/websiite: document query strings for /dl more prominently Oct 13, 2019
@gopherbot gopherbot added this to the Unreleased milestone Oct 13, 2019
@mvdan
Copy link
Member

@mvdan mvdan commented Oct 13, 2019

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.

@agnivade agnivade changed the title x/websiite: document query strings for /dl more prominently x/website: document query strings for /dl more prominently Oct 13, 2019
@dmitshur
Copy link
Member

@dmitshur dmitshur commented Oct 13, 2019

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.

@dmitshur dmitshur changed the title x/website: document query strings for /dl more prominently x/website: decide whether to document /dl?mode=json API more prominently Oct 13, 2019
@mvdan
Copy link
Member

@mvdan mvdan commented Oct 13, 2019

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
Copy link
Contributor

@theckman theckman commented Apr 5, 2020

@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
Copy link
Member

@mvdan mvdan commented Apr 5, 2020

@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
Copy link
Contributor

@rsc rsc commented Apr 22, 2020

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.

@rsc rsc added the NeedsFix label Apr 22, 2020
@dmitshur dmitshur changed the title x/website: decide whether to document /dl?mode=json API more prominently x/website: document /dl?mode=json API more prominently Apr 22, 2020
@dmitshur
Copy link
Member

@dmitshur dmitshur commented Apr 22, 2020

@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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
7 participants
You can’t perform that action at this time.