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 tohttps://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 tohttps://api.github.com
.stack
(list of plugins): Plugins to control the execution of client requests. SeeGitHub.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
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
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"}
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.
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.
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},
# ...
]