Configuration for the API client and plugins

Note

Functions in this module is unlikely to be used directly by applications. Instead, they are useful for plugins. See GitHub.Plugin for more information.

Callers of API operation functions can pass in some configuration directly using the final argument. Configuration passed in this way always takes precedence over global configuration.

# Local options:
GitHub.Repos.get("aj-foster", "open-api-github", server: "https://gh.example.com")

# Application environment (ex. config/config.exs):
config :oapi_github, server: "https://gh.example.com"

options

Options

The following configuration is available using local options:

• server (URL): API server to use. Useful if the client would like to target a GitHub Enterprise installation. Defaults to https://api.github.com.

• stack (list of plugins): Plugins to control the execution of client requests. See GitHub.Plugin for more information. Defaults to the default stack below.

• version (string): API version to use. Setting this option is not recommended, as the default value is the version of the API used to generate this client's code. Overriding it risks the client raising an error. To see the default value, open .api-version in the root of this project.

• wrap (boolean): Whether to wrap the results of the API call in a tagged tuple. When true, the response body will be wrapped as {:ok, response} on success or {:error, error} otherwise. When false, the Operation or Error is returned directly. Defaults to true.

  Note: Unwrapped responses violate the type specifications provided for each client operation. To avoid Dialyzer errors, consider using GitHub.raw/4 instead.

The following configuration is available using the application environment:

• app_name (string): Name of the application using this client, used for User Agent and logging purposes.

• apps (list of tuples): GitHub App configurations. Each app config is a 3-tuple containing a name (atom), app ID (integer), and private key (string, PEM format). See GitHub.app/1 for more information.

• default_auth (GitHub.Auth.auth/0): Default API authentication credentials to use when authentication was not provided for a request. OAuth applications can provide their client ID and secret to increase their unauthenticated rate limit.

• server (URL): API server to use. Useful if the client would like to target a GitHub Enterprise installation. Defaults to https://api.github.com.

• stack (list of plugins): Plugins to control the execution of client requests. See GitHub.Plugin for more information. Defaults to the default stack below.

• webhook_secret (string): Secret value provided to GitHub for signing webhook requests. See GitHub.Webhook for more information. Defaults to no signature verification.

plugins

Plugins

Client requests are implemented using a series of plugins. Each plugin accepts a GitHub.Operation struct and returns either a modified operation or an error. The collection of plugins configured for a request form a stack.

The default stack uses Jason as a serializer/deserializer and HTTPoison as an HTTP client:

[
  {GitHub.Plugin.JasonSerializer, :encode_body, []},
  {GitHub.Plugin.HTTPoisonClient, :request, []},
  {GitHub.Plugin.JasonSerializer, :decode_body, []},
  {GitHub.Plugin.TypedDecoder, :decode_response, []},
  {GitHub.Plugin.TypedDecoder, :normalize_errors, []}
]

In general, plugins can be defined as 2- or 3-tuples specifying the module and function name and any options to pass to the function. For example:

{MyPlugin, :my_function}
#=> MyPlugin.my_function(operation)

{MyPlugin, :my_function, some: :option}
#=> MyPlugin.my_function(operation, some: :option)

By modifying the stack, applications can easily use a different HTTP client library or serializer.

Warning

Stack entries without options, like {GitHub.Plugin.TestClient, :request}, look like keyword list items. If you have stacks configured in multiple Mix environments that all use this 2-tuple format, Elixir will try to merge them as keyword lists. Adding an empty options element to any stack item will prevent this behaviour.