View Source GitHub.Config (GitHub REST API Client v0.0.1)

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.

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.

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

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.

Link to this section Summary

Types

Plugin definition

Functions

Get the configured app name

Get the configured default auth credentials

Get configuration namespaced with a plugin module

Get configuration namespaced with a plugin module, or raise if not present

Get the configured default API server, or https://api.github.com by default

Get the configured plugin stack

Link to this section Types

@type plugin() ::
  {module :: module(), function :: atom(), options :: keyword()}
  | {module :: module(), function :: atom()}

Plugin definition

Plugins are defined in the stack using module and function tuples with an optional keyword list. Options, if provided, will be passed as the second argument.

Link to this section Functions

@spec app_name() :: String.t() | nil

Get the configured app name

example

Example

iex> Config.app_name()
"Test App"
@spec default_auth() :: GitHub.Auth.auth()

Get the configured default auth credentials

example

Example

iex> Config.default_auth()
{"client_one", "abc123"}
Link to this function

plugin_config(config \\ [], plugin, key, default)

View Source
@spec plugin_config(keyword(), module(), atom(), term()) :: term()

Get configuration namespaced with a plugin module

Plugins can provide a keyword list of options (such as a pre-merged keyword list of the plugin options argument and the operation's options) to be used if the given key is present. Otherwise, the response will fall back to the application environment given with the following form:

config :oapi_github, MyPlugin, some: :option

Where MyPlugin is the plugin module given as the second argument.

See plugin_config!/3 for a variant that raises if the configuration is not found.

Link to this function

plugin_config!(config \\ [], plugin, key)

View Source
@spec plugin_config!(keyword(), module(), atom()) :: term() | no_return()

Get configuration namespaced with a plugin module, or raise if not present

Plugins can provide a keyword list of options (such as a pre-merged keyword list of the plugin options argument and the operation's options) to be used if the given key is present. Otherwise, the response will fall back to the application environment given with the following form:

config :oapi_github, MyPlugin, some: :option

Where MyPlugin is the plugin module given as the second argument.

See plugin_config/4 for a variant that accepts a default value.

@spec server(keyword()) :: String.t()

Get the configured default API server, or https://api.github.com by default

example

Example

iex> Config.server([])
"https://api.github.com"

iex> Config.server(server: "https://gh.example.com")
"https://gh.example.com"
@spec stack() :: [plugin()]

Get the configured plugin stack

example

Example

iex> Config.stack()
[
  {GitHub.Plugin.JasonSerializer, :encode_body},
  # ...
]