[website] _content/blog: add pkgsite api blog post
10 views
Skip to first unread message
Ethan Lee (Gerrit)
May 7, 2026, 7:42:27 PM (12 days ago) May 7
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Ethan Lee has uploaded the change for review![]( "Open in Gerrit")
Commit message
_content/blog: add pkgsite api blog post
To preview this CL, download it and:
$ go run ./cmd/golangorg &
$ open http://localhost:6060/go.dev/blog/pkgsite-api
Change-Id: I5dea660902b660319c0647d83794d7f90ede773a
Change diff
diff --git a/_content/blog/pkgsite-api.md b/_content/blog/pkgsite-api.md
new file mode 100644
index 0000000..3efdb8d
--- /dev/null
+++ b/_content/blog/pkgsite-api.md
@@ -0,0 +1,93 @@
+---
+title: Introducing the pkg.go.dev API
+date: 2026-05-11
+by:
+- Ethan Lee
+- Hana Kim
+- Jonathan Amsterdam
+summary: Introducing the new programmatic API for pkg.go.dev, allowing developers to fetch package and module data directly.
+---
+
+Since its inception, [pkg.go.dev](https://pkg.go.dev) has established itself as the primary resource for Go package documentation and discovery. While we initially prioritized creating a best-in-class web interface for users, the need for programmatic access has become increasingly clear. Developers building tools, IDE integrations, and automated workflows have historically relied on fragile workarounds like web scraping to access this data. To better address these evolving requirements, we are now expanding our platform to provide robust, direct access to the information our community needs.
+
+Today, we are excited to introduce the official [pkg.go.dev](https://pkg.go.dev) API - a stable interface for querying metadata about published Go modules. This launch is a direct response to years of community feedback. Furthermore, the need for a formalized interface has become even more acute with the rise of AI-assisted coding. Now there is the ability to access specific, high-fidelity context needed to reason about the Go ecosystem with significantly greater precision.
+
+## Motivations
+
+The primary goal of the new API is to provide the Go community programmatic access to structured, high-quality data from [pkg.go.dev](https://pkg.go.dev). The API supports use cases like these:
+
+* **Programmatic Search:** Tools can now find relevant packages based on keywords and receive structured JSON responses.
+* **Discovering Package Importers:** One of our most requested features, this allows maintainers to understand their user base and the potential impact of breaking changes.
+* **AI and LLM Integration:** The API provides a way for large language models and agents to retrieve "just-in-time" context about Go packages, ensuring they utilize the latest library versions and documentation available in the registry.
+
+## The Service Interface
+
+Built for stability and efficient caching, the API utilizes a stateless, GET-only architecture. Primary endpoints are currently hosted under the `/v1beta` path. Following a period of community feedback and confirmed stability, we intend to transition toward a formal v1 release.
+
+### Core Endpoints
+
+| Endpoint | Description |
+| :--- | :--- |
+| `/v1beta/package/{path}` | Information about the package at {path}. |
+| `/v1beta/module/{path}` | Information about the module at {path}. |
+| `/v1beta/versions/{path}` | Versions of the module at {path}. |
+| `/v1beta/packages/{path}` | Information about packages of the module at {path}. |
+| `/v1beta/search` | Search results. |
+| `/v1beta/symbols/{path}` | List of symbols declared by the package at {path}. |
+| `/v1beta/imported-by/{path}` | Paths of packages importing the package at {path}. |
+| `/v1beta/vulns/{path}` | Vulnerabilities of the module at {path}. |
+
+One design principle for this API is **Precision over Convenience**. Unlike the Go command or [pkg.go.dev](https://pkg.go.dev) UI, which use "longest module path" shortcuts, the API requires explicit resolution. If a path is ambiguous, the API returns a list of candidates to force tools to be explicit about which dependency is being queried.
+
+### Example: Raw API Request
+
+To retrieve structured metadata for a specific package directly:
+
+```bash
+$ curl https://pkg.go.dev/v1beta/package/encoding/json
+```
+
+**JSON Response:**
+```json
+{
+ "modulePath": "std",
+ "version": "v1.26.3",
+ "isLatest": true,
+ "isStandardLibrary": true,
+ "goos": "all",
+ "goarch": "all",
+ "path": "encoding/json",
+ "name": "json",
+ "synopsis": "Package json implements encoding and decoding of JSON as defined in RFC 7159.",
+ "isRedistributable": true
+}
+```
+
+## The pkgsite-cli Reference Implementation
+
+To demonstrate how to interact with our API, we are providing a reference CLI implementation: `pkgsite-cli`. This implementation serves as a practical example for developers looking to build their own integrations, showing how to handle the data directly from the terminal. Please be aware that as the API continues to evolve, the interface and behavior of this CLI remain subject to adjustment.
+
+You can use it to search for packages, inspect symbols, and more without leaving your shell:
+
+```bash
+$ go install golang.org/x/pkgsite/cmd/internal/pkgsite-cli@latest
+
+$ pkgsite-cli search "http client"
+net/http
+ Module: s...@v1.26.3
+ Synopsis: Package http provides HTTP client and server implementations.
+... more
+
+$ pkgsite-cli package encoding/json
+encoding/json (standard library)
+ Name: json
+ Module: std
+ Version: v1.26.3 (latest)
+ Synopsis: Package json implements encoding and decoding of JSON as defined in RFC 7159.
+```
+
+The CLI handles pagination and formatting, allowing you to focus on the data you need for your scripts or manual investigation.To learn more, please visit pkgsite-cli’s documentation.
+
+## Stability and the Future
+
+This release establishes the initial foundation for our API. We are prioritizing stability for programmatic access, ensuring that tools built on top of this interface continue to work as [pkg.go.dev](https://pkg.go.dev) evolves. As we continue to refine this API, we welcome your feedback via our [issue tracker](https://github.com/golang/go/issues). We look forward to seeing the new tools and integrations the community will build.
\ No newline at end of file
Change information
Files:
- A _content/blog/pkgsite-api.md
Change size: M
Delta: 1 file changed, 93 insertions(+), 0 deletions(-)
Related details
Attention set is empty
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 7, 2026, 7:43:48 PM (12 days ago) May 7
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention needed from Ethan Lee
Ethan Lee uploaded new patchset![]( "Open in Gerrit")
Ethan Lee uploaded patch set #2 to this change.
Related details
Attention is currently required from:
- Ethan Lee
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 7, 2026, 7:45:36 PM (12 days ago) May 7
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention needed from Ethan Lee
Ethan Lee uploaded new patchset![]( "Open in Gerrit")
Ethan Lee uploaded patch set #3 to this change.
Related details
Attention is currently required from:
- Ethan Lee
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 7, 2026, 7:49:18 PM (12 days ago) May 7
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention needed from Ethan Lee
Ethan Lee uploaded new patchset![]( "Open in Gerrit")
Ethan Lee uploaded patch set #4 to this change.
Related details
Attention is currently required from:
- Ethan Lee
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 7, 2026, 7:51:52 PM (12 days ago) May 7
to goph...@pubsubhelper.golang.org, Jonathan Amsterdam, Hyang-Ah Hana Kim, Alan Donovan, golang...@luci-project-accounts.iam.gserviceaccount.com, golang-co...@googlegroups.com
Attention needed from Alan Donovan, Hyang-Ah Hana Kim and Jonathan Amsterdam
Ethan Lee added 1 comment![]( "Open in Gerrit")
Patchset-level comments
File-level comment, Patchset 4 (Latest):
Ethan Lee . resolved
Draft CL taken directly from the doc, please feel free to review it in its final form and/or add other reviewers.
Related details
Attention is currently required from:
- Alan Donovan
- Hyang-Ah Hana Kim
- Jonathan Amsterdam
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 7, 2026, 7:52:31 PM (12 days ago) May 7
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention needed from Alan Donovan, Ethan Lee, Hyang-Ah Hana Kim and Jonathan Amsterdam
Ethan Lee uploaded new patchset![]( "Open in Gerrit")
Attention is currently required from:
- Alan Donovan
- Ethan Lee
- Hyang-Ah Hana Kim
- Jonathan Amsterdam
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Alan Donovan (Gerrit)
May 8, 2026, 1:13:36 PM (11 days ago) May 8
to Ethan Lee, goph...@pubsubhelper.golang.org, golang...@luci-project-accounts.iam.gserviceaccount.com, Jonathan Amsterdam, Hyang-Ah Hana Kim, golang-co...@googlegroups.com
Attention needed from Ethan Lee, Hyang-Ah Hana Kim and Jonathan Amsterdam
Alan Donovan added 21 comments![]( "Open in Gerrit")
File _content/blog/pkgsite-api.md
Line 11, Patchset 5 (Latest):
Since its inception, [pkg.go.dev](https://pkg.go.dev) has established itself as the primary resource for Go package documentation and discovery. While we initially prioritized creating a best-in-class web interface for users, the need for programmatic access has become increasingly clear. Developers building tools, IDE integrations, and automated workflows have historically relied on fragile workarounds like web scraping to access this data. To better address these evolving requirements, we are now expanding our platform to provide robust, direct access to the information our community needs.Alan Donovan . unresolved
This phrase is overused by salespeople. Can we describe what makes it best in whatever class it inhabits?
Line 11, Patchset 5 (Latest):
Since its inception, [pkg.go.dev](https://pkg.go.dev) has established itself as the primary resource for Go package documentation and discovery. While we initially prioritized creating a best-in-class web interface for users, the need for programmatic access has become increasingly clear. Developers building tools, IDE integrations, and automated workflows have historically relied on fragile workarounds like web scraping to access this data. To better address these evolving requirements, we are now expanding our platform to provide robust, direct access to the information our community needs.Alan Donovan . unresolved
primary for whom? Perhaps "the Go community's primary resource for package..."?
Line 13, Patchset 5 (Latest):
Today, we are excited to introduce the official [pkg.go.dev](https://pkg.go.dev) API - a stable interface for querying metadata about published Go modules. This launch is a direct response to years of community feedback. Furthermore, the need for a formalized interface has become even more acute with the rise of AI-assisted coding. Now there is the ability to access specific, high-fidelity context needed to reason about the Go ecosystem with significantly greater precision.Alan Donovan . unresolved
service interface?
Line 13, Patchset 5 (Latest):
Today, we are excited to introduce the official [pkg.go.dev](https://pkg.go.dev) API - a stable interface for querying metadata about published Go modules. This launch is a direct response to years of community feedback. Furthermore, the need for a formalized interface has become even more acute with the rise of AI-assisted coding. Now there is the ability to access specific, high-fidelity context needed to reason about the Go ecosystem with significantly greater precision.Alan Donovan . unresolved
This sentence could be tighter, and should use the active voice.
Line 13, Patchset 5 (Latest):
Today, we are excited to introduce the official [pkg.go.dev](https://pkg.go.dev) API - a stable interface for querying metadata about published Go modules. This launch is a direct response to years of community feedback. Furthermore, the need for a formalized interface has become even more acute with the rise of AI-assisted coding. Now there is the ability to access specific, high-fidelity context needed to reason about the Go ecosystem with significantly greater precision.Alan Donovan . unresolved
An em dash (sans spaces) is appropriate here. Don't be afraid to use them just because the robot hacks overdo it!
Line 19, Patchset 5 (Latest):
* **Programmatic Search:** Tools can now find relevant packages based on keywords and receive structured JSON responses.Alan Donovan . unresolved
Can this be a link to the actual JSON schema?
I notice that the schemas for the `package` and `module` JSON outputs are not the same as (or a superset of) the output of `go list -json` and `go list -m -json`. Is that intentional? (Feel free to direct me to the design docs rather than rehash the design here.)
```
$ go list -m -json go.starlark.net@latest
{
"Path": "go.starlark.net",
"Version": "v0.0.0-20260326113308-fadfc96def35",
"Query": "latest",
"Time": "2026-03-26T11:33:08Z",
"GoMod": "/Users/adonovan/go/pkg/mod/cache/download/go.starlark.net/@v/v0.0.0-20260326113308-fadfc96def35.mod",
"GoVersion": "1.25.0"
}
$ pkgsite-cli module -json go.starlark.net
{
"module": {
"path": "go.starlark.net",
"version": "v0.0.0-20260326113308-fadfc96def35",
"isLatest": true,
"isRedistributable": true,
"isStandardLibrary": false,
"hasGoMod": true,
"repoUrl": "https://github.com/google/starlark-go"
}
```
Might it be worth converging them while we still have the opportunity?
Line 19, Patchset 5 (Latest):
* **Programmatic Search:** Tools can now find relevant packages based on keywords and receive structured JSON responses.Alan Donovan . unresolved
s
(capitalize only the first word)
Line 21, Patchset 5 (Latest):
* **AI and LLM Integration:** The API provides a way for large language models and agents to retrieve "just-in-time" context about Go packages, ensuring they utilize the latest library versions and documentation available in the registry.Alan Donovan . unresolved
use
(utilize is almost never the right word)
Line 21, Patchset 5 (Latest):
* **AI and LLM Integration:** The API provides a way for large language models and agents to retrieve "just-in-time" context about Go packages, ensuring they utilize the latest library versions and documentation available in the registry.Alan Donovan . unresolved
Let's avoid this word since Go modules don't aren't "registered": the index and proxy are merely a feed and cache of modules that have ever been downloaded by the go command.
Line 23, Patchset 5 (Latest):
## The Service InterfaceAlan Donovan . unresolved
Oonly the first word of each blog heading is typically capitalized.
Line 25, Patchset 5 (Latest):
Built for stability and efficient caching, the API utilizes a stateless, GET-only architecture. Primary endpoints are currently hosted under the `/v1beta` path. Following a period of community feedback and confirmed stability, we intend to transition toward a formal `v1` release.Alan Donovan . unresolved
uses
Line 40, Patchset 5 (Latest):
One design principle for this API is **Precision over Convenience**. Unlike the Go command or [pkg.go.dev](https://pkg.go.dev) UI, which use "longest module path" shortcuts, the API requires explicit resolution. If a path is ambiguous, the API returns a list of candidates to force tools to be explicit about which dependency is being queried.Alan Donovan . unresolved
I wonder why this ambiguity is important if the go command always consistently picks a specific resolution.
Line 40, Patchset 5 (Latest):
One design principle for this API is **Precision over Convenience**. Unlike the Go command or [pkg.go.dev](https://pkg.go.dev) UI, which use "longest module path" shortcuts, the API requires explicit resolution. If a path is ambiguous, the API returns a list of candidates to force tools to be explicit about which dependency is being queried.Alan Donovan . unresolved
Use quotation marks, not capitals.
Line 68, Patchset 5 (Latest):
To demonstrate how to interact with our API, we are providing a reference CLI implementation: [pkgsite-cli](https://github.com/golang/pkgsite/tree/master/cmd/internal/pkgsite-cli). This implementation serves as a practical example for developers looking to build their own integrations, showing how to handle the data directly from the terminal. Please be aware that as the API continues to evolve, the interface and behavior of this CLI remain subject to adjustment.Alan Donovan . unresolved
command
Line 68, Patchset 5 (Latest):
To demonstrate how to interact with our API, we are providing a reference CLI implementation: [pkgsite-cli](https://github.com/golang/pkgsite/tree/master/cmd/internal/pkgsite-cli). This implementation serves as a practical example for developers looking to build their own integrations, showing how to handle the data directly from the terminal. Please be aware that as the API continues to evolve, the interface and behavior of this CLI remain subject to adjustment.Alan Donovan . unresolved
client
(CLI means "command-line interface", but here the role of the pkgsite-cli command is not as an interface--we explicitly disclaim its interface stability at the end of this paragraph0--but as a reference implementation of a client of the service.)
Line 104, Patchset 5 (Latest):
Alan Donovan . unresolved
It would be nice to show a few more examples here.
BTW, I tried this command and got:
```
$ pkgsite-cli package --limit=99999 --imported-by go.starlark.net/starlark
go.starlark.net/starlark
Name: starlark
Module: go.starlark.net
Version: v0.0.0-20260326113308-fadfc96def35 (latest)
Imported by:
agola.io/agola/internal/config
...
Showing 1000 of 1209. Use --limit=N to see more.
```
Even with the limit flag, the result is still truncated. Is that a bug?
Also the -doc flag appears not to be working as documented:
```
$ pkgsite-cli package -help
...
Flags:
-doc string
render docs in format: text, md, html
...
$ pkgsite-cli package -doc=text go.starlark.net/starlark | head
go.starlark.net/starlark
Name: starlark
Module: go.starlark.net
Version: v0.0.0-20260326113308-fadfc96def35 (latest)
$ pkgsite-cli package -doc=nonesuch go.starlark.net/starlark | head
go.starlark.net/starlark
Name: starlark
Module: go.starlark.net
Version: v0.0.0-20260326113308-fadfc96def35 (latest)
```
Also -symbols:
```
$ pkgsite-cli package -symbols go.starlark.net/starlark
not found (HTTP 404)
```
Line 105, Patchset 5 (Latest):
The CLI handles pagination and formatting, allowing you to focus on the data you need for your scripts or manual investigation.To learn more, please visit [pkgsite-cli’s documentation](https://github.com/golang/pkgsite/blob/master/doc/pkgsite-cli.md).Alan Donovan . unresolved
space after period
Line 105, Patchset 5 (Latest):
The CLI handles pagination and formatting, allowing you to focus on the data you need for your scripts or manual investigation.To learn more, please visit [pkgsite-cli’s documentation](https://github.com/golang/pkgsite/blob/master/doc/pkgsite-cli.md).Alan Donovan . unresolved
command
Line 109, Patchset 5 (Latest):
This release establishes the initial foundation for our API. We are prioritizing stability for programmatic access, ensuring that tools built on top of this interface continue to work as [pkg.go.dev](https://pkg.go.dev) evolves. As we continue to refine this API, we welcome your feedback via our [issue tracker](https://github.com/golang/go/issues). We look forward to seeing the new tools and integrations the community will build.Alan Donovan . unresolved
the service interface
Line 109, Patchset 5 (Latest):
This release establishes the initial foundation for our API. We are prioritizing stability for programmatic access, ensuring that tools built on top of this interface continue to work as [pkg.go.dev](https://pkg.go.dev) evolves. As we continue to refine this API, we welcome your feedback via our [issue tracker](https://github.com/golang/go/issues). We look forward to seeing the new tools and integrations the community will build.Alan Donovan . unresolved
interface
Related details
Attention is currently required from:
- Ethan Lee
- Hyang-Ah Hana Kim
- Jonathan Amsterdam
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Hyang-Ah Hana Kim (Gerrit)
May 8, 2026, 3:21:12 PM (11 days ago) May 8
to Ethan Lee, goph...@pubsubhelper.golang.org, golang...@luci-project-accounts.iam.gserviceaccount.com, Jonathan Amsterdam, Hyang-Ah Hana Kim, Alan Donovan, golang-co...@googlegroups.com
Attention needed from Ethan Lee and Jonathan Amsterdam
Hyang-Ah Hana Kim added 1 comment![]( "Open in Gerrit")
File _content/blog/pkgsite-api.md
Line 40, Patchset 5 (Latest):
One design principle for this API is **Precision over Convenience**. Unlike the Go command or [pkg.go.dev](https://pkg.go.dev) UI, which use "longest module path" shortcuts, the API requires explicit resolution. If a path is ambiguous, the API returns a list of candidates to force tools to be explicit about which dependency is being queried.Alan Donovan . unresolved
I wonder why this ambiguity is important if the go command always consistently picks a specific resolution.
Hyang-Ah Hana Kim
it's tru that `go get` from empty dependency always picks one, but other go commands can pick a different one with the same name depending on what's in go.mod.
e.g.
```
$ cat main.go
package main
import "github.com/hyangah/retracttest/d"
func main() {
println(d.D)
}
$ go get github.com/hyangah/retra...@v0.2.0
$ go mod tidy
$ go doc d.D
package d // import "github.com/hyangah/retracttest/d"var D = 1 // THIS IS ONE!!!
$ go get github.com/hyangah/retracttest@none
go: removed github.com/hyangah/retracttest v0.2.0
$ go mod tidy
go: finding module for package github.com/hyangah/retracttest/d
go: found github.com/hyangah/retracttest/d in github.com/hyangah/retracttest/d v0.2.0
$ go doc d.D
package d // import "github.com/hyangah/retracttest/d"
var D = 2 // THIS IS TWO!!!
```
pkg.go.dev decided to show the longest match.
The API instead chose to request the client to clarify which module path to use.
Related details
Attention is currently required from:
- Ethan Lee
- Jonathan Amsterdam
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 8, 2026, 6:14:16 PM (11 days ago) May 8
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention needed from Ethan Lee and Jonathan Amsterdam
Ethan Lee uploaded new patchset![]( "Open in Gerrit")
Ethan Lee uploaded patch set #6 to this change.
Following approvals got outdated and were removed:
- TryBots-Pass: LUCI-TryBot-Result+1 by golang...@luci-project-accounts.iam.gserviceaccount.com
Related details
Attention is currently required from:
- Ethan Lee
- Jonathan Amsterdam
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 8, 2026, 6:15:34 PM (11 days ago) May 8
to goph...@pubsubhelper.golang.org, golang...@luci-project-accounts.iam.gserviceaccount.com, Jonathan Amsterdam, Hyang-Ah Hana Kim, Alan Donovan, golang-co...@googlegroups.com
Attention needed from Alan Donovan and Jonathan Amsterdam
Ethan Lee voted and added 18 comments![]( "Open in Gerrit")
Votes added by Ethan Lee
| Auto-Submit | +1 |
18 comments
File _content/blog/pkgsite-api.md
Line 11, Patchset 5:
Since its inception, [pkg.go.dev](https://pkg.go.dev) has established itself as the primary resource for Go package documentation and discovery. While we initially prioritized creating a best-in-class web interface for users, the need for programmatic access has become increasingly clear. Developers building tools, IDE integrations, and automated workflows have historically relied on fragile workarounds like web scraping to access this data. To better address these evolving requirements, we are now expanding our platform to provide robust, direct access to the information our community needs.Alan Donovan . resolved
This phrase is overused by salespeople. Can we describe what makes it best in whatever class it inhabits?
Ethan Lee
Done
Line 11, Patchset 5:
Since its inception, [pkg.go.dev](https://pkg.go.dev) has established itself as the primary resource for Go package documentation and discovery. While we initially prioritized creating a best-in-class web interface for users, the need for programmatic access has become increasingly clear. Developers building tools, IDE integrations, and automated workflows have historically relied on fragile workarounds like web scraping to access this data. To better address these evolving requirements, we are now expanding our platform to provide robust, direct access to the information our community needs.Alan Donovan . resolved
primary for whom? Perhaps "the Go community's primary resource for package..."?
Ethan Lee
Done
Line 13, Patchset 5:
Today, we are excited to introduce the official [pkg.go.dev](https://pkg.go.dev) API - a stable interface for querying metadata about published Go modules. This launch is a direct response to years of community feedback. Furthermore, the need for a formalized interface has become even more acute with the rise of AI-assisted coding. Now there is the ability to access specific, high-fidelity context needed to reason about the Go ecosystem with significantly greater precision.Alan Donovan . resolved
Ethan Leeservice interface?
Done
Line 13, Patchset 5:
Today, we are excited to introduce the official [pkg.go.dev](https://pkg.go.dev) API - a stable interface for querying metadata about published Go modules. This launch is a direct response to years of community feedback. Furthermore, the need for a formalized interface has become even more acute with the rise of AI-assisted coding. Now there is the ability to access specific, high-fidelity context needed to reason about the Go ecosystem with significantly greater precision.Alan Donovan . unresolved
An em dash (sans spaces) is appropriate here. Don't be afraid to use them just because the robot hacks overdo it!
Ethan Lee
Sure, but looks like
Line 13, Patchset 5:
Today, we are excited to introduce the official [pkg.go.dev](https://pkg.go.dev) API - a stable interface for querying metadata about published Go modules. This launch is a direct response to years of community feedback. Furthermore, the need for a formalized interface has become even more acute with the rise of AI-assisted coding. Now there is the ability to access specific, high-fidelity context needed to reason about the Go ecosystem with significantly greater precision.Alan Donovan . unresolved
This sentence could be tighter, and should use the active voice.
Ethan Lee
Done
Line 19, Patchset 5:
* **Programmatic Search:** Tools can now find relevant packages based on keywords and receive structured JSON responses.Alan Donovan . resolved
s
(capitalize only the first word)
Ethan Lee
Done
Line 21, Patchset 5:
* **AI and LLM Integration:** The API provides a way for large language models and agents to retrieve "just-in-time" context about Go packages, ensuring they utilize the latest library versions and documentation available in the registry.Alan Donovan . resolved
use
(utilize is almost never the right word)
Ethan Lee
Done
Line 21, Patchset 5:
* **AI and LLM Integration:** The API provides a way for large language models and agents to retrieve "just-in-time" context about Go packages, ensuring they utilize the latest library versions and documentation available in the registry.Alan Donovan . resolved
Let's avoid this word since Go modules don't aren't "registered": the index and proxy are merely a feed and cache of modules that have ever been downloaded by the go command.
Ethan Lee
Done
Oonly the first word of each blog heading is typically capitalized.
Ethan Lee
Done
Line 25, Patchset 5:
Built for stability and efficient caching, the API utilizes a stateless, GET-only architecture. Primary endpoints are currently hosted under the `/v1beta` path. Following a period of community feedback and confirmed stability, we intend to transition toward a formal `v1` release.Alan Donovan . resolved
Ethan Leeuses
Done
Line 40, Patchset 5:
One design principle for this API is **Precision over Convenience**. Unlike the Go command or [pkg.go.dev](https://pkg.go.dev) UI, which use "longest module path" shortcuts, the API requires explicit resolution. If a path is ambiguous, the API returns a list of candidates to force tools to be explicit about which dependency is being queried.Alan Donovan . resolved
Use quotation marks, not capitals.
Ethan Lee
Done
Line 68, Patchset 5:
To demonstrate how to interact with our API, we are providing a reference CLI implementation: [pkgsite-cli](https://github.com/golang/pkgsite/tree/master/cmd/internal/pkgsite-cli). This implementation serves as a practical example for developers looking to build their own integrations, showing how to handle the data directly from the terminal. Please be aware that as the API continues to evolve, the interface and behavior of this CLI remain subject to adjustment.Alan Donovan . resolved
Ethan Leecommand
Done
Line 68, Patchset 5:
To demonstrate how to interact with our API, we are providing a reference CLI implementation: [pkgsite-cli](https://github.com/golang/pkgsite/tree/master/cmd/internal/pkgsite-cli). This implementation serves as a practical example for developers looking to build their own integrations, showing how to handle the data directly from the terminal. Please be aware that as the API continues to evolve, the interface and behavior of this CLI remain subject to adjustment.Alan Donovan . resolved
client
(CLI means "command-line interface", but here the role of the pkgsite-cli command is not as an interface--we explicitly disclaim its interface stability at the end of this paragraph0--but as a reference implementation of a client of the service.)
Ethan Lee
Done
Line 105, Patchset 5:
The CLI handles pagination and formatting, allowing you to focus on the data you need for your scripts or manual investigation.To learn more, please visit [pkgsite-cli’s documentation](https://github.com/golang/pkgsite/blob/master/doc/pkgsite-cli.md).Alan Donovan . resolved
Ethan Leecommand
Done
Line 105, Patchset 5:
The CLI handles pagination and formatting, allowing you to focus on the data you need for your scripts or manual investigation.To learn more, please visit [pkgsite-cli’s documentation](https://github.com/golang/pkgsite/blob/master/doc/pkgsite-cli.md).Alan Donovan . resolved
Ethan Leespace after period
Done
Line 109, Patchset 5:
This release establishes the initial foundation for our API. We are prioritizing stability for programmatic access, ensuring that tools built on top of this interface continue to work as [pkg.go.dev](https://pkg.go.dev) evolves. As we continue to refine this API, we welcome your feedback via our [issue tracker](https://github.com/golang/go/issues). We look forward to seeing the new tools and integrations the community will build.Alan Donovan . resolved
Ethan Leeinterface
Done
Line 109, Patchset 5:
This release establishes the initial foundation for our API. We are prioritizing stability for programmatic access, ensuring that tools built on top of this interface continue to work as [pkg.go.dev](https://pkg.go.dev) evolves. As we continue to refine this API, we welcome your feedback via our [issue tracker](https://github.com/golang/go/issues). We look forward to seeing the new tools and integrations the community will build.Alan Donovan . resolved
Ethan Leethe service interface
Done
Related details
Attention is currently required from:
- Alan Donovan
- Jonathan Amsterdam
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 8, 2026, 7:38:30 PM (11 days ago) May 8
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention needed from Alan Donovan, Ethan Lee and Jonathan Amsterdam
Ethan Lee uploaded new patchset![]( "Open in Gerrit")
Ethan Lee uploaded patch set #7 to this change.
Following approvals got outdated and were removed:
- TryBots-Pass: LUCI-TryBot-Result+1 by golang...@luci-project-accounts.iam.gserviceaccount.com
Related details
Attention is currently required from:
- Alan Donovan
- Ethan Lee
- Jonathan Amsterdam
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 8, 2026, 7:38:54 PM (11 days ago) May 8
to goph...@pubsubhelper.golang.org, golang...@luci-project-accounts.iam.gserviceaccount.com, Jonathan Amsterdam, Hyang-Ah Hana Kim, Alan Donovan, golang-co...@googlegroups.com
Attention needed from Alan Donovan, Ethan Lee and Jonathan Amsterdam
Ethan Lee voted and added 4 comments![]( "Open in Gerrit")
Votes added by Ethan Lee
| Auto-Submit | +1 |
| Commit-Queue | +1 |
4 comments
File _content/blog/pkgsite-api.md
Line 13, Patchset 5:
Today, we are excited to introduce the official [pkg.go.dev](https://pkg.go.dev) API - a stable interface for querying metadata about published Go modules. This launch is a direct response to years of community feedback. Furthermore, the need for a formalized interface has become even more acute with the rise of AI-assisted coding. Now there is the ability to access specific, high-fidelity context needed to reason about the Go ecosystem with significantly greater precision.Alan Donovan . resolved
An em dash (sans spaces) is appropriate here. Don't be afraid to use them just because the robot hacks overdo it!
Ethan Lee
Sure, but looks like
Ethan Lee
Done
Line 13, Patchset 5:
Today, we are excited to introduce the official [pkg.go.dev](https://pkg.go.dev) API - a stable interface for querying metadata about published Go modules. This launch is a direct response to years of community feedback. Furthermore, the need for a formalized interface has become even more acute with the rise of AI-assisted coding. Now there is the ability to access specific, high-fidelity context needed to reason about the Go ecosystem with significantly greater precision.Alan Donovan . resolved
This sentence could be tighter, and should use the active voice.
Ethan Lee
Ethan LeeDone
Done
Line 19, Patchset 5:
* **Programmatic Search:** Tools can now find relevant packages based on keywords and receive structured JSON responses.Alan Donovan . unresolved
Can this be a link to the actual JSON schema?
I notice that the schemas for the `package` and `module` JSON outputs are not the same as (or a superset of) the output of `go list -json` and `go list -m -json`. Is that intentional? (Feel free to direct me to the design docs rather than rehash the design here.)
```
$ go list -m -json go.starlark.net@latest
{
"Path": "go.starlark.net",
"Version": "v0.0.0-20260326113308-fadfc96def35",
"Query": "latest",
"Time": "2026-03-26T11:33:08Z",
"GoMod": "/Users/adonovan/go/pkg/mod/cache/download/go.starlark.net/@v/v0.0.0-20260326113308-fadfc96def35.mod",
"GoVersion": "1.25.0"
}
$ pkgsite-cli module -json go.starlark.net
{
"module": {
"path": "go.starlark.net",
"version": "v0.0.0-20260326113308-fadfc96def35",
"isLatest": true,
"isRedistributable": true,
"isStandardLibrary": false,
"hasGoMod": true,
"repoUrl": "https://github.com/google/starlark-go"
}
```Might it be worth converging them while we still have the opportunity?
Ethan Lee
The schema for the API output was intentionally designed to reflect relevant data directly from the database, similar to the current operation of pkgsite. Because the API serves as a window into the global index rather than a local build tool, we prioritized mapping to the database structure for efficiency. Converging them would require either omitting database-specific fields or including data that go list doesn't provide.
Design doc link: go/pkgsite-rest-api
Ethan Lee
Thanks the first one was a bug, that I have a CL out for.
For the second one, it seems to be working:
```
$ pkgsite-cli package -doc=text go.starlark.net/starlark | head
go.starlark.net/starlark
Name: starlark
Module: go.starlark.net
Version: v0.0.0-20260326113308-fadfc96def35 (latest)
Synopsis: Package starlark provides a Starlark interpreter.
package starlark
Package starlark provides a Starlark interpreter.
$ pkgsite-cli package -doc=nonesuch go.starlark.net/starlark | head
bad doc format: need one of 'text', 'md', 'markdown' or 'html' (HTTP 400)
```
The third one resolves to this:
```
$ pkgsite-cli package -symbols go.starlark.net/starlark
go.starlark.net/starlark
Name: starlark
Module: go.starlark.net
Version: v0.0.0-20260326113308-fadfc96def35 (latest)
Synopsis: Package starlark provides a Starlark interpreter.
Symbols:
type Binding struct{ ... }
type Bool bool
type Builtin struct{}
type Bytes string
type CallFrame struct{ ... }
type CallStack []CallFrame
type Callable interface{ ... }
type Comparable interface{ ... }
type Container interface{ ... }
type DebugFrame interface{ ... }
```
Related details
Attention is currently required from:
- Alan Donovan
- Ethan Lee
- Jonathan Amsterdam
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 8, 2026, 7:39:20 PM (11 days ago) May 8
to goph...@pubsubhelper.golang.org, golang...@luci-project-accounts.iam.gserviceaccount.com, Jonathan Amsterdam, Hyang-Ah Hana Kim, Alan Donovan, golang-co...@googlegroups.com
Attention needed from Alan Donovan and Jonathan Amsterdam
Ethan Lee added 1 comment![]( "Open in Gerrit")
File _content/blog/pkgsite-api.md
Attention is currently required from:
- Alan Donovan
- Jonathan Amsterdam
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 8, 2026, 7:40:48 PM (11 days ago) May 8
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention needed from Alan Donovan, Ethan Lee and Jonathan Amsterdam
Ethan Lee uploaded new patchset![]( "Open in Gerrit")
Attention is currently required from:
- Alan Donovan
- Ethan Lee
- Jonathan Amsterdam
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Jonathan Amsterdam (Gerrit)
May 10, 2026, 10:44:44 AM (9 days ago) May 10
to Ethan Lee, goph...@pubsubhelper.golang.org, golang...@luci-project-accounts.iam.gserviceaccount.com, Hyang-Ah Hana Kim, Alan Donovan, golang-co...@googlegroups.com
Attention needed from Alan Donovan and Ethan Lee
Jonathan Amsterdam added 1 comment![]( "Open in Gerrit")
File _content/blog/pkgsite-api.md
Line 40, Patchset 5:
One design principle for this API is **Precision over Convenience**. Unlike the Go command or [pkg.go.dev](https://pkg.go.dev) UI, which use "longest module path" shortcuts, the API requires explicit resolution. If a path is ambiguous, the API returns a list of candidates to force tools to be explicit about which dependency is being queried.Jonathan Amsterdam
The go command and pkg.go.dev are both user-facing tools that aim for a pleasant experience. Part of that is to streamline interactions by choosing sensible defaults. The API has a different goal: to provide comprehensive, accurate information about the Go ecosystem. For that task, it makes sense to require unambiguous queries.
Related details
Attention is currently required from:
- Alan Donovan
- Ethan Lee
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Alan Donovan (Gerrit)
May 11, 2026, 11:00:24 AM (8 days ago) May 11
to Ethan Lee, goph...@pubsubhelper.golang.org, golang...@luci-project-accounts.iam.gserviceaccount.com, Jonathan Amsterdam, Hyang-Ah Hana Kim, golang-co...@googlegroups.com
Attention needed from Ethan Lee
Alan Donovan added 5 comments![]( "Open in Gerrit")
File _content/blog/pkgsite-api.md
Alan Donovan
Ah. It's not really a "shortcut" in the sense that it's by definition the canonical definition of the build semantics. Can we be more explicit about what we're being explicit about? Perhaps something along the lines of:
For example, the package imported as `example.com/a/b/c` could be provided by module `example.com/a` or by `example.com/a/b`. If both exist, the Go command the [pkg.go.dev](https://pkg.go.dev) web interface always choose the one with the longest possible module path. (This flexibility makes it possible to later "carve out" a submodule from an existing module without breaking builds.) However, the pkg.go.dev query interface will in this case return a list of candidates to force tools to be explicit about which dependency is being queried.
Line 47, Patchset 8 (Latest):
$ curl https://pkg.go.dev/v1beta/package/encoding/json | jqAlan Donovan . unresolved
What is jq doing for us here? (Don't assume readers know what it is.)
Line 78, Patchset 8 (Latest):
```bash
$ pkgsite-cli search "http client"
```
**Command output:**
```textAlan Donovan . unresolved
Is it necessary to add a separate block for the output? Using single block keeps related things together:
```
$ echo hello
hello
```
Alan Donovan
Thanks the first one was a bug, that I have a CL out for.
Good; let's make sure that fix is in the `latest` release before publishing the post.
For the second one, it seems to be working:
Still not working for me. In fact it is working even less than before:
```
tools$ pwd
/Users/adonovan/x/tools
tools$ go install golang.org/x/pkgsite/cmd/internal/pkgsite-cli@latest
tools$ pkgsite-cli package -doc=text go.starlark.net/starlark
HTTP 404: Not Found
```
The third is similarly not working.
Line 108, Patchset 8 (Latest):
$ pkgsite-cli package --imported-by encoding/jsonAlan Donovan . unresolved
All commands are failing for me:
```
$ pkgsite-cli package --imported-by encoding/json
HTTP 404: Not Found
```
Related details
Attention is currently required from:
- Ethan Lee
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 11, 2026, 11:16:53 AM (8 days ago) May 11
to goph...@pubsubhelper.golang.org, golang...@luci-project-accounts.iam.gserviceaccount.com, Jonathan Amsterdam, Hyang-Ah Hana Kim, Alan Donovan, golang-co...@googlegroups.com
Attention needed from Alan Donovan
Ethan Lee added 1 comment![]( "Open in Gerrit")
File _content/blog/pkgsite-api.md
Ethan Lee
Of course, we want to release only once we have everything polished and production ready. I just sent out the blog post CL to gather feedback early (and it's been invaluable).
Regarding the 404 errors, that's expected, we pushed a new change and the deployments happen periodically. I will manually re-trigger the build and get back to you.
Related details
Attention is currently required from:
- Alan Donovan
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 12, 2026, 2:43:46 PM (7 days ago) May 12
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention needed from Alan Donovan and Ethan Lee
Ethan Lee uploaded new patchset![]( "Open in Gerrit")
Ethan Lee uploaded patch set #9 to this change.
Following approvals got outdated and were removed:
- TryBots-Pass: LUCI-TryBot-Result+1 by golang...@luci-project-accounts.iam.gserviceaccount.com
Related details
Attention is currently required from:
- Alan Donovan
- Ethan Lee
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 12, 2026, 2:46:28 PM (7 days ago) May 12
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention needed from Alan Donovan and Ethan Lee
Ethan Lee uploaded new patchset![]( "Open in Gerrit")
Ethan Lee uploaded patch set #10 to this change.
Related details
Attention is currently required from:
- Alan Donovan
- Ethan Lee
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 12, 2026, 2:49:51 PM (7 days ago) May 12
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention needed from Alan Donovan and Ethan Lee
Ethan Lee uploaded new patchset![]( "Open in Gerrit")
Ethan Lee uploaded patch set #11 to this change.
Related details
Attention is currently required from:
- Alan Donovan
- Ethan Lee
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 12, 2026, 2:50:07 PM (7 days ago) May 12
to goph...@pubsubhelper.golang.org, golang...@luci-project-accounts.iam.gserviceaccount.com, Jonathan Amsterdam, Hyang-Ah Hana Kim, Alan Donovan, golang-co...@googlegroups.com
Attention needed from Alan Donovan, Ethan Lee, Hyang-Ah Hana Kim and Jonathan Amsterdam
Ethan Lee voted and added 3 comments![]( "Open in Gerrit")
Votes added by Ethan Lee
| Auto-Submit | +1 |
3 comments
File _content/blog/pkgsite-api.md
Ethan Lee
Changed, it let me know what you think.
Line 47, Patchset 8:
$ curl https://pkg.go.dev/v1beta/package/encoding/json | jqAlan Donovan . resolved
What is jq doing for us here? (Don't assume readers know what it is.)
Ethan Lee
Done
Line 78, Patchset 8:
```bash
$ pkgsite-cli search "http client"
```
**Command output:**
```textAlan Donovan . resolved
Is it necessary to add a separate block for the output? Using single block keeps related things together:
```
$ echo hello
hello
```
Attention is currently required from:
- Alan Donovan
- Ethan Lee
- Hyang-Ah Hana Kim
- Jonathan Amsterdam
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Jonathan Amsterdam (Gerrit)
May 12, 2026, 8:17:42 PM (6 days ago) May 12
to Ethan Lee, goph...@pubsubhelper.golang.org, golang...@luci-project-accounts.iam.gserviceaccount.com, Hyang-Ah Hana Kim, Alan Donovan, golang-co...@googlegroups.com
Attention needed from Alan Donovan, Ethan Lee and Hyang-Ah Hana Kim
Jonathan Amsterdam voted Code-Review+2![]( "Open in Gerrit")
| Code-Review | +2 |
Related details
Attention is currently required from:
- Alan Donovan
- Ethan Lee
- Hyang-Ah Hana Kim
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Alan Donovan (Gerrit)
May 12, 2026, 10:05:46 PM (6 days ago) May 12
to Ethan Lee, goph...@pubsubhelper.golang.org, Jonathan Amsterdam, golang...@luci-project-accounts.iam.gserviceaccount.com, Hyang-Ah Hana Kim, golang-co...@googlegroups.com
Attention needed from Ethan Lee and Hyang-Ah Hana Kim
Alan Donovan added 4 comments![]( "Open in Gerrit")
File _content/blog/pkgsite-api.md
Line 19, Patchset 5:
* **Programmatic Search:** Tools can now find relevant packages based on keywords and receive structured JSON responses.Alan Donovan . unresolved
Ethan LeeCan this be a link to the actual JSON schema?
I notice that the schemas for the `package` and `module` JSON outputs are not the same as (or a superset of) the output of `go list -json` and `go list -m -json`. Is that intentional? (Feel free to direct me to the design docs rather than rehash the design here.)
```
$ go list -m -json go.starlark.net@latest
{
"Path": "go.starlark.net",
"Version": "v0.0.0-20260326113308-fadfc96def35",
"Query": "latest",
"Time": "2026-03-26T11:33:08Z",
"GoMod": "/Users/adonovan/go/pkg/mod/cache/download/go.starlark.net/@v/v0.0.0-20260326113308-fadfc96def35.mod",
"GoVersion": "1.25.0"
}
$ pkgsite-cli module -json go.starlark.net
{
"module": {
"path": "go.starlark.net",
"version": "v0.0.0-20260326113308-fadfc96def35",
"isLatest": true,
"isRedistributable": true,
"isStandardLibrary": false,
"hasGoMod": true,
"repoUrl": "https://github.com/google/starlark-go"
}
```Might it be worth converging them while we still have the opportunity?
The schema for the API output was intentionally designed to reflect relevant data directly from the database, similar to the current operation of pkgsite. Because the API serves as a window into the global index rather than a local build tool, we prioritized mapping to the database structure for efficiency. Converging them would require either omitting database-specific fields or including data that go list doesn't provide.
Design doc link: go/pkgsite-rest-api
Alan Donovan
I see. Can we add a link from this section to the official schema description, wherever that is?
Alan Donovan
Is the issue that the request schema for the pkg.go.dev service requires the caller to provide a pair (module, pkgdir), whereas the web interface and the go command, by splitting a path using the "longest module" algorithm, do not?
I think it might be clearer to include the explanation in the parenthesis above as to why it is crucial that the go command and pkg.go.dev accept both forms: it's to support compatible evolution. Otherwise it raises the question of why the go command permits ambiguity, surely that's a bad thing?
Line 47, Patchset 11 (Latest):
$ curl https://pkg.go.dev/v1beta/package/encoding/json | jqAlan Donovan . unresolved
I get a big HTML 404 page from this command.
Alan Donovan
Why is it reporting 404s at all, for commands that you already ran successfully (i.e. for server functionality that was already deployed)? That's a little strange.
Related details
Attention is currently required from:
- Ethan Lee
- Hyang-Ah Hana Kim
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 13, 2026, 11:00:57 AM (6 days ago) May 13
to goph...@pubsubhelper.golang.org, Jonathan Amsterdam, golang...@luci-project-accounts.iam.gserviceaccount.com, Hyang-Ah Hana Kim, Alan Donovan, golang-co...@googlegroups.com
Attention needed from Alan Donovan and Hyang-Ah Hana Kim
Ethan Lee added 1 comment![]( "Open in Gerrit")
File _content/blog/pkgsite-api.md
Ethan Lee
We changed the endpoint in a recent change, but then some other change broke the deployment. The root cause is known; the fix is in progress.
Related details
Attention is currently required from:
- Alan Donovan
- Hyang-Ah Hana Kim
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Alan Donovan (Gerrit)
May 13, 2026, 3:30:21 PM (6 days ago) May 13
to Ethan Lee, goph...@pubsubhelper.golang.org, Jonathan Amsterdam, golang...@luci-project-accounts.iam.gserviceaccount.com, Hyang-Ah Hana Kim, golang-co...@googlegroups.com
Attention needed from Ethan Lee and Hyang-Ah Hana Kim
Alan Donovan added 1 comment![]( "Open in Gerrit")
File _content/blog/pkgsite-api.md
Attention is currently required from:
- Ethan Lee
- Hyang-Ah Hana Kim
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Sean Liao (Gerrit)
May 16, 2026, 2:27:46 PM (3 days ago) May 16
to Ethan Lee, goph...@pubsubhelper.golang.org, Jonathan Amsterdam, golang...@luci-project-accounts.iam.gserviceaccount.com, Hyang-Ah Hana Kim, Alan Donovan, golang-co...@googlegroups.com
Attention needed from Ethan Lee and Hyang-Ah Hana Kim
Sean Liao added 5 comments![]( "Open in Gerrit")
File _content/blog/pkgsite-api.md
Sean Liao
+1 having actual docs that describe the api would be really useful, including all the optional query parameters.
Line 32, Patchset 11 (Latest):
| `/v1beta/module/{path}` | Information about the module at `{path}`. |Sean Liao . unresolved
somewhat unintuitively, it returns the response of the containing module if path is a package (e.g. golang.org/x/sync/errgroup)
This is different from go list -m which requires the argument be an actual module
Line 34, Patchset 11 (Latest):
| `/v1beta/packages/{path}` | Information about packages of the module at `{path}`. |Sean Liao . unresolved
same as above, it returns info for the module containing the package at path, rather than the module at the path, or a filtered view
Line 36, Patchset 11 (Latest):
| `/v1beta/symbols/{path}` | List of symbols declared by the package at `{path}`. |Sean Liao . unresolved
Symbols probably deserves an example, it's also unclear if / how to expand the response to include things like methods?
```
url -s https://pkg.go.dev/v1beta/symbols/golang.org/x/sync/singleflight | jq .
{
"modulePath": "golang.org/x/sync",
"version": "v0.20.0",
"symbols": {
"items": [
{
"name": "Group",
"kind": "Type",
"synopsis": "type Group struct{}",
"parent": "Group"
},
{
"name": "Result",
"kind": "Type",
"synopsis": "type Result struct{ ... }",
"parent": "Result"
}
],
"total": 2
}
}
```
Line 31, Patchset 11 (Latest):
| `/v1beta/package/{path}` | Information about the package at `{path}`. |
| `/v1beta/module/{path}` | Information about the module at `{path}`. |
| `/v1beta/versions/{path}` | Versions of the module at `{path}`. |
| `/v1beta/packages/{path}` | Information about packages of the module at `{path}`. |
| `/v1beta/search?q={query}` | Search results for a given query. |
| `/v1beta/symbols/{path}` | List of symbols declared by the package at `{path}`. |
| `/v1beta/imported-by/{path}` | Paths of packages importing the package at `{path}`. |
| `/v1beta/vulns/{path}` | Vulnerabilities of the module at `{path}`. |Sean Liao . unresolved
The immediate question i have is, where / how are versions specified?
Related details
Attention is currently required from:
- Ethan Lee
- Hyang-Ah Hana Kim
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 18, 2026, 11:00:30 PM (9 hours ago) May 18
to goph...@pubsubhelper.golang.org, Jonathan Amsterdam, golang...@luci-project-accounts.iam.gserviceaccount.com, Hyang-Ah Hana Kim, Alan Donovan, golang-co...@googlegroups.com
Attention needed from Alan Donovan, Hyang-Ah Hana Kim, Jonathan Amsterdam and Sean Liao
Ethan Lee added 5 comments![]( "Open in Gerrit")
File _content/blog/pkgsite-api.md
Ethan Lee
Yeah I have added links in the `service interface` section to both pkg.go.dev/api and pkg.go.dev/v1beta/openapi.yaml.
Line 32, Patchset 11 (Latest):
| `/v1beta/module/{path}` | Information about the module at `{path}`. |Sean Liao . unresolved
somewhat unintuitively, it returns the response of the containing module if path is a package (e.g. golang.org/x/sync/errgroup)
This is different from go list -m which requires the argument be an actual module
Ethan Lee
Thanks, I think that's a good point and we are reconsidering the behavior if the path supplied is a package rather than a module. Will update this when that change lands.
Line 36, Patchset 11 (Latest):
| `/v1beta/symbols/{path}` | List of symbols declared by the package at `{path}`. |Sean Liao . unresolved
Symbols probably deserves an example, it's also unclear if / how to expand the response to include things like methods?
```
url -s https://pkg.go.dev/v1beta/symbols/golang.org/x/sync/singleflight | jq .
{
"modulePath": "golang.org/x/sync",
"version": "v0.20.0",
"symbols": {
"items": [
{
"name": "Group",
"kind": "Type",
"synopsis": "type Group struct{}",
"parent": "Group"
},
{
"name": "Result",
"kind": "Type",
"synopsis": "type Result struct{ ... }",
"parent": "Result"
}
],
"total": 2
}
}
```
Ethan Lee
That's a great point, I will add a relevant example. But first, I will change the way the symbols are returned and add filtering based on symbol kind.
Line 31, Patchset 11 (Latest):
| `/v1beta/package/{path}` | Information about the package at `{path}`. |
| `/v1beta/module/{path}` | Information about the module at `{path}`. |
| `/v1beta/versions/{path}` | Versions of the module at `{path}`. |
| `/v1beta/packages/{path}` | Information about packages of the module at `{path}`. |
| `/v1beta/search?q={query}` | Search results for a given query. |
| `/v1beta/symbols/{path}` | List of symbols declared by the package at `{path}`. |
| `/v1beta/imported-by/{path}` | Paths of packages importing the package at `{path}`. |
| `/v1beta/vulns/{path}` | Vulnerabilities of the module at `{path}`. |Sean Liao . resolved
The immediate question i have is, where / how are versions specified?
Ethan Lee
That's a good point, I added some clarification for this!
Ethan Lee
I think that makes sense, I added the flexibility explanation to hopefully make clear that intention behind the design choice.
Related details
Attention is currently required from:
- Alan Donovan
- Hyang-Ah Hana Kim
- Jonathan Amsterdam
- Sean Liao
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Ethan Lee (Gerrit)
May 18, 2026, 11:00:42 PM (9 hours ago) May 18
to goph...@pubsubhelper.golang.org, golang-co...@googlegroups.com
Attention needed from Alan Donovan, Ethan Lee, Hyang-Ah Hana Kim, Jonathan Amsterdam and Sean Liao
Ethan Lee uploaded new patchset![]( "Open in Gerrit")
Ethan Lee uploaded patch set #12 to this change.
Following approvals got outdated and were removed:
- TryBots-Pass: LUCI-TryBot-Result+1 by golang...@luci-project-accounts.iam.gserviceaccount.com
Related details
Attention is currently required from:
- Alan Donovan
- Ethan Lee
- Hyang-Ah Hana Kim
- Jonathan Amsterdam
- Sean Liao
Submit Requirements:
Code-Review
No-Unresolved-Comments
Review-Enforcement
TryBots-Pass
| Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings. |
Reply all
Reply to author
Forward
0 new messages