_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 Reviewed-on: https://go-review.googlesource.com/c/website/+/775580 LUCI-TryBot-Result: golang-scoped@luci-project-accounts.iam.gserviceaccount.com <golang-scoped@luci-project-accounts.iam.gserviceaccount.com> Auto-Submit: Ethan Lee <ethanalee@google.com> Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com> Reviewed-by: Jonathan Amsterdam <jba@google.com> Reviewed-by: Alan Donovan <adonovan@google.com>
diff --git a/_content/blog/pkgsite-api.md b/_content/blog/pkgsite-api.md new file mode 100644 index 0000000..48dfe3d --- /dev/null +++ b/_content/blog/pkgsite-api.md
@@ -0,0 +1,244 @@ +--- +title: Introducing the pkg.go.dev API +date: 2026-05-21 +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 Go community's primary resource for package documentation and discovery. +While we initially prioritized creating a comprehensive and highly accessible +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 API](https://pkg.go.dev/api) — a service 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. +Tools can now access the specific, high-fidelity context needed to reason +about the Go ecosystem with greater precision. + +## The service interface + +Built for stability and efficient caching, the API uses 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. + +For a complete interactive reference of all endpoints, query parameters, and +response shapes, see the [pkg.go.dev/api specification](https://pkg.go.dev/api). +The machine-readable API contract is also published directly as an [OpenAPI +specification](https://pkg.go.dev/v1beta/openapi.yaml). + +### 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?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 or package at `{path}`. | + +One design principle for this API is "precision over convenience." For context, +when `go mod tidy` encounters an import of a package that isn't provided by an +existing dependency of the main module, it applies the "longest module path" +rule to determine which module is needed. (The fact that two or more modules +could provide the package is what makes it possible to later carve out a +submodule without breaking existing programs.) The +[pkg.go.dev](https://pkg.go.dev) web interface follows a similar convention +when choosing which package to display for a given package path. +By contrast, the [pkg.go.dev](https://pkg.go.dev) API requires the module to be +specified unambiguously. If a package path is ambiguous because it exists in +multiple modules, the API returns a list of candidates and reports an error +asking the client to be more specific. + +For example, a package imported as `example.com/a/b/c` could be provided by +module `example.com/a` or by `example.com/a/b`. While the +[pkg.go.dev](https://pkg.go.dev) web interface will automatically resolve the +"longest module path" (`example.com/a/b`), a client querying the API must +specify the module explicitly to avoid an ambiguous resolution error. + +### Specifying versions + +For endpoints that retrieve package, module, or symbol information, you can +specify the desired version using the optional `version` query parameter. The +API returns information about the latest version of the module or package by +default. The parameter supports: + +* **Semantic Versions:** Retrieve data for a specific release tag (e.g., + `?version=v1.2.3` or `?version=v0.6.0`). +* **Branch Names:** Reference default development branches—specifically `master` + or `main` (e.g., `?version=master`). The API will automatically resolve the + branch to its corresponding pseudo-version. Note that custom or arbitrary + branch names are not supported. + +If the `version` parameter is omitted, the API defaults to resolving the +request against the latest tagged version of the package or module. + +### Example: raw API request + +To retrieve structured metadata for a specific package directly (using `jq` for +formatting): + +```console +$ curl https://pkg.go.dev/v1beta/package/github.com/google/go-cmp/cmp | jq . +{ + "modulePath": "github.com/google/go-cmp", + "version": "v0.7.0", + "isLatest": true, + "isStandardLibrary": false, + "goos": "all", + "goarch": "all", + "path": "github.com/google/go-cmp/cmp", + "name": "cmp", + "synopsis": "Package cmp determines equality of values.", + "isRedistributable": true +} +``` + +To query a specific branch version (like `master`) and see it resolve +automatically to its corresponding pseudo-version: + +```console +$ curl -s "https://pkg.go.dev/v1beta/package/github.com/google/go-cmp/cmp?version=master" | jq '{path, version}' +{ + "path": "github.com/google/go-cmp/cmp", + "version": "v0.7.1-0.20260310220054-34c9473539b8" +} +``` + +## The pkgsite-cli reference implementation + +To demonstrate how to interact with our API, we are providing a reference +client 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 command may change. + +To get started, install the command: + +```bash +$ go install golang.org/x/pkgsite/cmd/internal/pkgsite-cli@latest +``` + +To search for packages: + +``` +$ pkgsite-cli search "uuid" +github.com/google/uuid + Module: github.com/google/uuid@v1.6.0 + Synopsis: Package uuid generates and inspects UUIDs. +... more +``` + +To inspect a specific package: + +``` +$ pkgsite-cli package github.com/google/go-cmp/cmp +github.com/google/go-cmp/cmp + Name: cmp + Module: github.com/google/go-cmp + Version: v0.7.0 (latest) + Synopsis: Package cmp determines equality of values. +``` + +To see which packages import a specific package: + +``` +$ pkgsite-cli package --imported-by github.com/google/go-cmp/cmp +github.com/google/go-cmp/cmp + Name: cmp + Module: github.com/google/go-cmp + Version: v0.7.0 (latest) + Synopsis: Package cmp determines equality of values. + +Imported by: + cloud.google.com/go/internal/testutil + cuelang.org/go/internal/cuetxtar + chainguard.dev/apko/pkg/build/types + ... more +``` + +To list symbols declared by a package: + +``` +$ pkgsite-cli package --symbols github.com/google/go-cmp/cmp +github.com/google/go-cmp/cmp + Name: cmp + Module: github.com/google/go-cmp + Version: v0.7.0 (latest) + Synopsis: Package cmp determines equality of values. + +Symbols: + type Indirect struct{} + type MapIndex struct{} + type Option interface{} + ... more +``` + +To list versions of a module: + +``` +$ pkgsite-cli module -versions github.com/google/go-cmp +github.com/google/go-cmp + Version: v0.7.0 (latest) + Repository: https://github.com/google/go-cmp + Has go.mod: yes + Redistributable: yes + +Versions: + v0.7.0 + v0.6.0 + v0.5.9 + ... more +``` + +To list both versions and packages of a module: + +``` +$ pkgsite-cli module -packages -versions github.com/google/go-cmp +github.com/google/go-cmp + Version: v0.7.0 (latest) + Repository: https://github.com/google/go-cmp + Has go.mod: yes + Redistributable: yes + +Versions: + v0.7.0 + v0.6.0 + v0.5.9 + ... more + +Packages: + github.com/google/go-cmp/cmp Package cmp determines equality of values. + github.com/google/go-cmp/cmp/cmpopts Package cmpopts provides common options for the cmp package. + ... more +``` + +The command 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://pkg.go.dev/golang.org/x/pkgsite/cmd/internal/pkgsite-cli). + +## Stability and the future + +This concludes our brief tour of the [pkg.go.dev](https://pkg.go.dev) API. While +we plan to expand the interface's capabilities over time, we are committed to +maintaining backward compatibility so that existing integrations continue to +function seamlessly. (Note that command line interface of the `pkgsite-cli` reference client is not yet stable.) We welcome your feedback via our [issue +tracker](https://github.com/golang/go/issues), and we look forward to seeing the +new tools and workflows the community will build.