pkg.go.dev APIの紹介

Introducing the pkg.go.dev API by Ethan Lee, Hana Kim, and Jonathan Amsterdam

pkg.go.dev は登場以来、パッケージのドキュメントと発見のためのGoコミュニティの主要なリソースとしての地位を確立してきました。私たちは当初、ユーザー向けに包括的で高いアクセシビリティを備えたWebインターフェースを作ることを優先していましたが、プログラムからのアクセスに対する需要はますます明らかになってきました。ツールやIDEの統合、自動化されたワークフローを構築する開発者たちは、これまでこのデータにアクセスするために、Webスクレイピングのような脆弱な回避策に頼らざるを得ませんでした。このような変化していくニーズによりよく応えるために、私たちは今、コミュニティが必要としている情報への堅牢で直接的なアクセスを提供するようプラットフォームを拡張しています。

本日、公開されているGoモジュールに関するメタデータを問い合わせるためのサービスインターフェースである、公式の pkg.go.dev API を発表できることを嬉しく思います。この公開は、長年にわたるコミュニティからのフィードバックに直接応えるものです。AIを活用したコーディングの台頭により、形式化されたインターフェースの必要性は一段と切実なものになっています。ツールは今や、Goのエコシステムについてより高い精度で推論するために必要な、具体的で忠実度の高いコンテキストにアクセスできるようになります。

サービスインターフェース

安定性と効率的なキャッシュのために設計されたこのAPIは、ステートレスでGETのみのアーキテクチャを採用しています。主要なエンドポイントは現在 /v1beta パス以下でホストされています。コミュニティからのフィードバックを受け、安定性が確認された後、正式な v1 リリースへと移行する予定です。

すべてのエンドポイント、クエリパラメータ、レスポンスの形式についての完全なインタラクティブなリファレンスは、 pkg.go.dev/api の仕様を参照してください。機械可読なAPI仕様は OpenAPI仕様としても直接公開されています。

主要なエンドポイント

エンドポイント	説明
`/v1beta/package/{path}`	`{path}` にあるパッケージの情報。
`/v1beta/module/{path}`	`{path}` にあるモジュールの情報。
`/v1beta/versions/{path}`	`{path}` にあるモジュールのバージョン一覧。
`/v1beta/packages/{path}`	`{path}` にあるモジュールが持つパッケージの情報。
`/v1beta/search?q={query}`	指定したクエリに対する検索結果。
`/v1beta/symbols/{path}`	`{path}` にあるパッケージが宣言するシンボルの一覧。
`/v1beta/imported-by/{path}`	`{path}` にあるパッケージをインポートしているパッケージのパス一覧。
`/v1beta/vulns/{path}`	`{path}` にあるモジュールまたはパッケージの脆弱性情報。

このAPIの設計原則の一つは「利便性より正確性」です。参考までに、 go mod tidy がメインモジュールの既存の依存関係によって提供されていないパッケージのインポートに遭遇すると、どのモジュールが必要かを判断するために「最も長いモジュールパス」規則を適用します。（複数のモジュールが同じパッケージを提供できるという事実こそが、既存のプログラムを壊すことなく後からサブモジュールを切り出すことを可能にしています。） pkg.go.dev のWebインターフェースは、あるパッケージパスに対してどのパッケージを表示するかを選ぶ際に、これと同様の慣習に従っています。対照的に、 pkg.go.dev APIはモジュールを曖昧さなく指定することを要求します。パッケージパスが複数のモジュールに存在するために曖昧である場合、APIは候補のリストを返し、クライアントにより具体的な指定を求めるエラーを報告します。

例えば、 example.com/a/b/c としてインポートされるパッケージは、モジュール example.com/a あるいは example.com/a/b のどちらからも提供されうるでしょう。 pkg.go.dev のWebインターフェースは自動的に「最も長いモジュールパス」（ example.com/a/b ）を解決しますが、APIに問い合わせるクライアントは、曖昧な解決によるエラーを避けるために明示的にモジュールを指定しなければなりません。

バージョンの指定

パッケージ、モジュール、あるいはシンボルの情報を取得するエンドポイントでは、任意の version クエリパラメータを使って希望するバージョンを指定できます。このパラメータを省略した場合、APIはデフォルトでモジュールあるいはパッケージの最新バージョンの情報を返します。このパラメータは次のものをサポートしています。

セマンティックバージョン： 特定のリリースタグのデータを取得します（例： ?version=v1.2.3 や ?version=v0.6.0 ）。
ブランチ名： デフォルトの開発ブランチ、具体的には master あるいは main を参照します（例： ?version=master ）。 APIは自動的にそのブランチを対応する疑似バージョンに解決します。任意のカスタムなブランチ名はサポートされていない点に注意してください。

version パラメータが省略された場合、APIはデフォルトでパッケージあるいはモジュールの最新のタグ付きバージョンに対してリクエストを解決します。

生のAPIリクエストの例

特定のパッケージの構造化されたメタデータを直接取得する例です（整形には jq を使用しています）。

$ 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
}

特定のブランチのバージョン（ master など）を問い合わせて、それが対応する疑似バージョンへ自動的に解決される様子を見てみましょう。

$ 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"
}

pkgsite-cliリファレンス実装

APIとの対話の仕方を示すために、リファレンスとなるクライアント実装 pkgsite-cli を提供しています。この実装は、独自の統合を構築しようとする開発者にとって、ターミナルから直接データを扱う方法を示す実践的な例になります。このコマンドのインターフェースと挙動は、APIの発展に伴って変わりうることに注意してください。

始めるには、次のコマンドをインストールします。

$ go install golang.org/x/pkgsite/cmd/internal/pkgsite-cli@latest

パッケージを検索するには次のようにします。

$ pkgsite-cli search "uuid"
github.com/google/uuid
  Module:   github.com/google/uuid@v1.6.0
  Synopsis: Package uuid generates and inspects UUIDs.
... more

特定のパッケージを調べるには次のようにします。

$ 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.

あるパッケージをどのパッケージがインポートしているかを見るには次のようにします。

$ 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

パッケージが宣言するシンボルの一覧を見るには次のようにします。

$ 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

モジュールのバージョン一覧を見るには次のようにします。

$ 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

モジュールのバージョンとパッケージの両方の一覧を見るには次のようにします。

$ 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

このコマンドはページネーションと整形を処理してくれるので、スクリプトや手動での調査に必要なデータに集中できます。詳しくは、 pkgsite-cliのドキュメントを参照してください。

安定性とこれから

以上で pkg.go.dev APIの簡単な紹介を終わります。今後もインターフェースの機能を拡張していく予定ですが、既存の統合がそのまま問題なく動作し続けるよう、後方互換性の維持に取り組んでいきます。（ pkgsite-cli リファレンスクライアントのコマンドラインインターフェース自体は、まだ安定していないことに注意してください。）イシュートラッカーを通じたフィードバックをお待ちしていますし、コミュニティが構築する新しいツールやワークフローを楽しみにしています。

By Ethan Lee, Hana Kim, and Jonathan Amsterdam