static/frontend/api/api.tmpl

<!--
  Copyright 2026 The Go Authors. All rights reserved.
  Use of this source code is governed by a BSD-style
  license that can be found in the LICENSE file.
-->

{{define "main"}}
  <style>
    .Api-list {
      list-style: none;
      padding: 0;
    }
    .Api-item {
      border-bottom: var(--border);
      display: flex;
      flex-direction: column;
      gap: 0.5rem;
      margin-bottom: 2rem;
      padding-bottom: 1rem;
    }
    .Api-item:last-child {
      border-bottom: none;
    }
    .Api-route {
      font-size: 1.25rem;
      font-weight: 600;
    }
    .Api-details {
      display: grid;
      gap: 0.5rem;
      grid-template-columns: 6rem 1fr;
    }
    .Api-label {
      font-weight: 600;
    }
    .Api-paramsTable {
      border-collapse: collapse;
      margin-top: 1.5rem;
      width: 100%;
    }
    .Api-paramsTable th {
      text-align: left;
      padding: 0.25rem 0.5rem;
      font-weight: 600;
    }
    .Api-paramsTable th:first-child {
      padding-left: 0;
    }
    .Api-paramsTable td {
      border-top: var(--border);
      vertical-align: top;
    }
    .Api-paramsTable td:first-child {
      padding-left: 0;
    }
  </style>
  <main class="go-Container" id="main-content">
    <div class="go-Content">
      <h1 data-test-id="api-heading">API Documentation</h1>
      <p>
        Pkgsite provides a JSON API for accessing information about
        Go packages and modules.
      </p>

      <h2>Requests</h2>
      <p>
      All requests are GET requests whose first URL segment selects the request
      type.
      Except for <code>search</code>, the remaining segments
      specify a module or package path. Additional arguments
      are specified as query parameters.
      </p>
      <p>
      Package paths are ambiguous: the same path <code>a/b/c</code> could be package
      <code>c</code> in module <code>a/b</code>
      or package <code>b/c</code> in module <code>a</code>.
      If both exist, the API returns an error with a list of possible modules in its
      <code>candidates</code> field.
      Make a follow-up request with the <code>module</code> query parameter to
      disambiguate. (Note: this behavior differs from the pkgsite UI, which selects
      the longest matching module path.)
      </p>
      <p>Some routes accept an optional <code>version</code> query parameter.
      If missing, the latest version is chosen.</p>

      <p>Some routes accept optional <code>GOOS</code> and <code>GOARCH</code>
      query parameters to select the desired build context of the documentation.
      If omitted, the default documentation build context is selected,
      typically <code>linux/amd64</code>.
      </p>

      <p>Some routes accept a <code>filter</code>, which selects only
      the items whose fields contain the filter as a substring. The
      documentation for each route specifies the filter behavior.
      </p>

      <h2>Responses</h2>
      <p>
        All routes return a JSON response.
        You can find a link to the corresponding Go type for a route in the documentation below.
        Errors are also returned as a JSON object, whose <code>message</code> field
        contains the error message.
      </p>
      <h2>Routes</h2>
      <ul class="Api-list">
        {{range .Routes}}
          <li class="Api-item">
            <div class="Api-route"><code>{{.Route}}</code></div>
            <p>{{.Desc}}</p>
            <div class="Api-details">
              {{if .QueryParams}}
                <span class="Api-label">Parameters:</span>
                <span>
                    <table class="Api-paramsTable">
                      <thead>
                        <tr>
                          <th>Name</th>
                          <th>Type</th>
                          <th>Description</th>
                        </tr>
                      </thead>
                      <tbody>
                          {{range .QueryParams}}
                            <tr>
                              <td><code>{{.Name}}</code></td>
                              <td><code>{{.Type}}</code></td>
                              <td>{{.Doc}}</td>
                            </tr>
                          {{end}}
                      </tbody>
                    </table>
                </span>
              {{end}} {{/* if .QueryParams */}}
              <span class="Api-label">Response:</span>
              <span><code>
                {{if .ResponsePaginatedType}}
                  <a href="https://pkg.go.dev/golang.org/x/pkgsite/internal/api#PaginatedResponse">PaginatedResponse</a>[{{if .LinkPaginatedType}}<a href="https://pkg.go.dev/golang.org/x/pkgsite/internal/api#{{.ResponsePaginatedType}}">{{.ResponsePaginatedType}}</a>{{else}}{{.ResponsePaginatedType}}{{end}}]
                {{else}}
                  <a href="https://pkg.go.dev/golang.org/x/pkgsite/internal/api#{{.Response}}">{{.Response}}</a>
                {{end}}
              </code></span>
            </div>
          </li>
        {{end}}
      </ul>
    </div>
  </main>
{{end}}