api

Documentation

Overview

Package api is a set of types for interacting with the GitHub API.

Index

• func DefaultHTTPClient() (*http.Client, error)
• func HandleHTTPError(resp *http.Response) error
• func NewHTTPClient(opts ClientOptions) (*http.Client, error)
• type ClientOptions
• type GraphQLClient
  • func DefaultGraphQLClient() (*GraphQLClient, error)
  • func NewGraphQLClient(opts ClientOptions) (*GraphQLClient, error)
  • func (c *GraphQLClient) Do(query string, variables map[string]interface{}, response interface{}) error
  • func (c *GraphQLClient) DoWithContext(ctx context.Context, query string, variables map[string]interface{}, ...) error
  • func (c *GraphQLClient) Mutate(name string, m interface{}, variables map[string]interface{}) error
  • func (c *GraphQLClient) MutateWithContext(ctx context.Context, name string, m interface{}, ...) error
  • func (c *GraphQLClient) Query(name string, q interface{}, variables map[string]interface{}) error
  • func (c *GraphQLClient) QueryWithContext(ctx context.Context, name string, q interface{}, ...) error
• type GraphQLError
  • func (gr *GraphQLError) Error() string
  • func (gr *GraphQLError) Match(expectType, expectPath string) bool
• type GraphQLErrorItem
• type HTTPError
  • func (err *HTTPError) Error() string
• type HTTPErrorItem
• type RESTClient
  • func DefaultRESTClient() (*RESTClient, error)
  • func NewRESTClient(opts ClientOptions) (*RESTClient, error)
  • func (c *RESTClient) Delete(path string, resp interface{}) error
  • func (c *RESTClient) Do(method string, path string, body io.Reader, response interface{}) error
  • func (c *RESTClient) DoWithContext(ctx context.Context, method string, path string, body io.Reader, ...) error
  • func (c *RESTClient) Get(path string, resp interface{}) error
  • func (c *RESTClient) Patch(path string, body io.Reader, resp interface{}) error
  • func (c *RESTClient) Post(path string, body io.Reader, resp interface{}) error
  • func (c *RESTClient) Put(path string, body io.Reader, resp interface{}) error
  • func (c *RESTClient) Request(method string, path string, body io.Reader) (*http.Response, error)
  • func (c *RESTClient) RequestWithContext(ctx context.Context, method string, path string, body io.Reader) (*http.Response, error)

Functions

func DefaultHTTPClient

func DefaultHTTPClient() (*http.Client, error)

func HandleHTTPError

func HandleHTTPError(resp *http.Response) error

HandleHTTPError parses a http.Response into a HTTPError.

func NewHTTPClient

func NewHTTPClient(opts ClientOptions) (*http.Client, error)

HTTPClient builds a client that can be passed to another library. As part of the configuration a hostname, auth token, default set of headers, and unix domain socket are resolved from the gh environment configuration. These behaviors can be overridden using the opts argument. In this instance providing opts.Host will not change the destination of your request as it is the responsibility of the consumer to configure this. However, if opts.Host does not match the request host, the auth token will not be added to the headers. This is to protect against the case where tokens could be sent to an arbitrary host.

Types

type ClientOptions

type ClientOptions struct {
	// AuthToken is the authorization token that will be used
	// to authenticate against API endpoints.
	AuthToken string

	// CacheDir is the directory to use for cached API requests.
	// Default is the same directory that gh uses for caching.
	CacheDir string

	// CacheTTL is the time that cached API requests are valid for.
	// Default is 24 hours.
	CacheTTL time.Duration

	// EnableCache specifies if API requests will be cached or not.
	// Default is no caching.
	EnableCache bool

	// Headers are the headers that will be sent with every API request.
	// Default headers set are Accept, Content-Type, Time-Zone, and User-Agent.
	// Default headers will be overridden by keys specified in Headers.
	Headers map[string]string

	// Host is the default host that API requests will be sent to.
	Host string

	// Log specifies a writer to write API request logs to. Default is to respect the GH_DEBUG environment
	// variable, and no logging otherwise.
	Log io.Writer

	// LogIgnoreEnv disables respecting the GH_DEBUG environment variable. This can be useful in test mode
	// or when the extension already offers its own controls for logging to the user.
	LogIgnoreEnv bool

	// LogColorize enables colorized logging to Log for display in a terminal.
	// Default is no coloring.
	LogColorize bool

	// LogVerboseHTTP enables logging HTTP headers and bodies to Log.
	// Default is only logging request URLs and response statuses.
	LogVerboseHTTP bool

	// SkipDefaultHeaders disables setting of the default headers.
	SkipDefaultHeaders bool

	// Timeout specifies a time limit for each API request.
	// Default is no timeout.
	Timeout time.Duration

	// Transport specifies the mechanism by which individual API requests are made.
	// If both Transport and UnixDomainSocket are specified then Transport takes
	// precedence. Due to this behavior any value set for Transport needs to manually
	// handle routing to UnixDomainSocket if necessary. Generally, setting Transport
	// should be reserved for testing purposes.
	// Default is http.DefaultTransport.
	Transport http.RoundTripper

	// UnixDomainSocket specifies the Unix domain socket address by which individual
	// API requests will be routed. If specifed, this will form the base of the API
	// request transport chain.
	// Default is no socket address.
	UnixDomainSocket string
}

ClientOptions holds available options to configure API clients.

type GraphQLClient

type GraphQLClient struct {
	// contains filtered or unexported fields
}

GraphQLClient wraps methods for the different types of API requests that are supported by the server.

func DefaultGraphQLClient

func DefaultGraphQLClient() (*GraphQLClient, error)

func NewGraphQLClient

func NewGraphQLClient(opts ClientOptions) (*GraphQLClient, error)

GraphQLClient builds a client to send requests to GitHub GraphQL API endpoints. As part of the configuration a hostname, auth token, default set of headers, and unix domain socket are resolved from the gh environment configuration. These behaviors can be overridden using the opts argument.

func (*GraphQLClient) Do

func (c *GraphQLClient) Do(query string, variables map[string]interface{}, response interface{}) error

Do wraps DoWithContext using context.Background.

func (*GraphQLClient) DoWithContext

func (c *GraphQLClient) DoWithContext(ctx context.Context, query string, variables map[string]interface{}, response interface{}) error

DoWithContext executes a GraphQL query request. The response is populated into the response argument.

func (*GraphQLClient) Mutate

func (c *GraphQLClient) Mutate(name string, m interface{}, variables map[string]interface{}) error

Mutate wraps MutateWithContext using context.Background.

func (*GraphQLClient) MutateWithContext

func (c *GraphQLClient) MutateWithContext(ctx context.Context, name string, m interface{}, variables map[string]interface{}) error

MutateWithContext executes a GraphQL mutation request. The mutation string is derived from the mutation argument, and the response is populated into it. The mutation argument should be a pointer to struct that corresponds to the GitHub GraphQL schema. Provided input will be set as a variable named input.

func (*GraphQLClient) Query

func (c *GraphQLClient) Query(name string, q interface{}, variables map[string]interface{}) error

Query wraps QueryWithContext using context.Background.

func (*GraphQLClient) QueryWithContext

func (c *GraphQLClient) QueryWithContext(ctx context.Context, name string, q interface{}, variables map[string]interface{}) error

QueryWithContext executes a GraphQL query request, The query string is derived from the query argument, and the response is populated into it. The query argument should be a pointer to struct that corresponds to the GitHub GraphQL schema.

type GraphQLError

type GraphQLError struct {
	Errors []GraphQLErrorItem
}

GraphQLError represents an error response from GitHub GraphQL API.

func (*GraphQLError) Error

func (gr *GraphQLError) Error() string

Allow GraphQLError to satisfy error interface.

func (*GraphQLError) Match

func (gr *GraphQLError) Match(expectType, expectPath string) bool

Match determines if the GraphQLError is about a specific type on a specific path. If the path argument ends with a ".", it will match all its subpaths.

type GraphQLErrorItem

type GraphQLErrorItem struct {
	Message   string
	Locations []struct {
		Line   int
		Column int
	}
	Path       []interface{}
	Extensions map[string]interface{}
	Type       string
}

GraphQLErrorItem stores additional information about an error response returned from the GitHub GraphQL API.

type HTTPError

type HTTPError struct {
	Errors     []HTTPErrorItem
	Headers    http.Header
	Message    string
	RequestURL *url.URL
	StatusCode int
}

HTTPError represents an error response from the GitHub API.

func (*HTTPError) Error

func (err *HTTPError) Error() string

Allow HTTPError to satisfy error interface.

type HTTPErrorItem

type HTTPErrorItem struct {
	Code     string
	Field    string
	Message  string
	Resource string
}

HTTPErrorItem stores additional information about an error response returned from the GitHub API.

type RESTClient

type RESTClient struct {
	// contains filtered or unexported fields
}

RESTClient wraps methods for the different types of API requests that are supported by the server.

func DefaultRESTClient

func DefaultRESTClient() (*RESTClient, error)

func NewRESTClient

func NewRESTClient(opts ClientOptions) (*RESTClient, error)

RESTClient builds a client to send requests to GitHub REST API endpoints. As part of the configuration a hostname, auth token, default set of headers, and unix domain socket are resolved from the gh environment configuration. These behaviors can be overridden using the opts argument.

func (*RESTClient) Delete

func (c *RESTClient) Delete(path string, resp interface{}) error

Delete issues a DELETE request to the specified path. The response is populated into the response argument.

func (*RESTClient) Do

func (c *RESTClient) Do(method string, path string, body io.Reader, response interface{}) error

Do wraps DoWithContext with context.Background.

func (*RESTClient) DoWithContext

func (c *RESTClient) DoWithContext(ctx context.Context, method string, path string, body io.Reader, response interface{}) error

DoWithContext issues a request with type specified by method to the specified path with the specified body. The response is populated into the response argument.

func (*RESTClient) Get

func (c *RESTClient) Get(path string, resp interface{}) error

Get issues a GET request to the specified path. The response is populated into the response argument.

func (*RESTClient) Patch

func (c *RESTClient) Patch(path string, body io.Reader, resp interface{}) error

Patch issues a PATCH request to the specified path with the specified body. The response is populated into the response argument.

func (*RESTClient) Post

func (c *RESTClient) Post(path string, body io.Reader, resp interface{}) error

Post issues a POST request to the specified path with the specified body. The response is populated into the response argument.

func (*RESTClient) Put

func (c *RESTClient) Put(path string, body io.Reader, resp interface{}) error

Put issues a PUT request to the specified path with the specified body. The response is populated into the response argument.

func (*RESTClient) Request

func (c *RESTClient) Request(method string, path string, body io.Reader) (*http.Response, error)

Request wraps RequestWithContext with context.Background.

func (*RESTClient) RequestWithContext

func (c *RESTClient) RequestWithContext(ctx context.Context, method string, path string, body io.Reader) (*http.Response, error)

RequestWithContext issues a request with type specified by method to the specified path with the specified body. The response is returned rather than being populated into a response argument.