API client

Active contributors: Mislav, Kynan, Corey Johnson

Purpose

The api/ package wraps cli/go-gh with GitHub-specific concerns: SSO redirect detection, OAuth scope hints in errors, telemetry headers, GraphQL feature flags, and a curated set of typed queries used throughout the CLI.

Directory layout

api/
  client.go                # NewClientFromHTTP, GraphQL/REST/Mutate/Query methods
  http_client.go           # Transport stack (auth, retry, sso, debug)
  query_builder.go         # GraphQL query reflection
  export_pr.go             # PR export to JSON
  export_repo.go           # Repo export to JSON
  reaction_groups.go       # Reaction renderers
  queries_repo.go          # ~46 KB of repository queries
  queries_pr.go            # ~25 KB of PR queries
  queries_pr_review.go     # PR review queries
  queries_issue.go         # Issue queries
  queries_comments.go      # Comment queries
  queries_org.go           # Organisation queries
  queries_projects_v2.go   # ProjectsV2 fragments
  queries_branch_issue_reference.go
  queries_user.go

Key abstractions

Symbol	File	Role
NewClientFromHTTP	client.go	Wraps an *http.Client and returns a *Client.
Client.GraphQL / Mutate / Query	client.go	Run a query string, a typed mutation, or a typed query.
Client.REST	client.go	Generic REST helper with JSON encoding.
Client.RESTWithNext	client.go	REST plus Link: rel="next" cursor for paginated calls.
HTTPError / GraphQLError	client.go	Typed errors carrying status, body, and ScopesSuggestion.
clientOptions	http_client.go	Builds go-gh api.ClientOptions with the canonical headers (X-GitHub-Api-Version: 2022-11-28, User-Agent, GraphQL-Features: merge_queue).
Pull request types	queries_pr.go	The PR domain model (PullRequest, Review, ReviewThread, ...).
Repository types	queries_repo.go	The repository domain model.

How it works

graph LR
    Cmd[pkg/cmd command] --> F[Factory.HttpClient]
    F --> T[http.RoundTripper stack]
    T --> RT[oauth header injection]
    T --> Hpd[httpretty debug -- if GH_DEBUG=api]
    T --> SSO[SSO header interceptor]
    T --> Tel[Telemetry header tagging]
    T --> Net[net/http]
    Net --> GitHub[GitHub API]
    GitHub --> Net
    Net -->|response| Decoder[handleResponse + JSON decode]
    Decoder --> Cmd

The transport stack is built by pkg/cmd/factory/default.go (HttpClientFunc). It composes:

1. The base http.Transport.
2. httpretty (only when GH_DEBUG=api).
3. SSO redirect detection: parses X-GitHub-SSO and exposes the URL via SSOURLRE.
4. OAuth scope hints: when a response has X-Accepted-OAuth-Scopes, the error string suggests gh auth refresh -s ....
5. Telemetry: tags the outgoing request with the invoking agent and CI signals so server-side dashboards can attribute traffic.

The same client is also used by gh api, which is essentially Client.REST and Client.GraphQL exposed through Cobra flags.

Integration points

• The host comes from cfg.Authentication().DefaultHost() everywhere; ghinstance.Default() is intentionally avoided.
• Pagination follows two conventions: REST uses Link: rel="next", GraphQL uses pageInfo.endCursor. Both are implemented in query_builder.go and RESTWithNext.
• All commands that talk to the API access it via f.HttpClient() and api.NewClientFromHTTP(httpClient). There is no global API client.

Entry points for modification

• New REST endpoint: add a typed helper to the relevant queries_*.go file and add a unit test in *_test.go. Use httpmock.Registry to assert the request shape.
• New GraphQL fragment: extend the matching queries_*.go file and update the query_builder tests if you change reflection-driven assembly.
• New transport behaviour: extend factory/default.go's HttpClientFunc so all callers benefit. Avoid wrapping per-command.

Key source files

File	Purpose
api/client.go	The Client type and request methods.
api/http_client.go	Headers, OAuth scope errors, SSO.
api/query_builder.go	GraphQL reflection and pagination.
api/queries_repo.go	Repository queries.
api/queries_pr.go	PR queries.
pkg/cmd/factory/default.go	Transport stack assembly.

Related pages

• gh api.
• Factory and cmdutil.
• Feature detection.