GitHub REST API Client v0.3.3

View Source GitHub.Plugin (GitHub REST API Client v0.3.3)

Plugins provide functionality for the API client

Note

This module is unlikely to be used directly by applications. The documentation contained here is useful for developers who would like to implement new functionality for the client.

This library has no opinions on how to complete API requests. Instead of requiring a particular HTTP client or JSON serializer, requests are completed using a series of plugins called a stack. To modify the behavior of the client, applications can add or modify plugins.

Plugins are functions that accept a GitHub.Operation struct — and any options — and return either an :ok or an :error tuple:

alias GitHub.{Error, Operation}

@spec my_plugin(Operation.t(), keyword) :: {:ok, Operation.t()} | {:error, Error.t()}
def my_plugin(operation, opts) do
  # ...
end

An :error tuple will immediately stop the stack and return the error. An :ok tuple will continue running the stack with the modified operation struct. If the stack concludes with a successful operation, the response_body is returned.

options

 Options

Plugins may accept options that modify their behavior. It is recommended that they consider options from three sources:

  1. Options passed to the operation function (available in the __opts__ key of the operation struct's private field). This is likely to include options not relevant to the plugin.
  2. Options passed to the plugin definition (available as the second argument of the plugin function).
  3. Options defined globally using the application environment.

This hierarchy can be accomplished by calling Keyword.merge/2 on the plugin options argument and the operation's options (order matters!), then calling GitHub.Config.plugin_config/4 to incorporate the application environment as a fallback. (For required options, the sibling function GitHub.Config.plugin_config!/3 is also available.)

In this way, plugins can be configured at all levels of the code:

# Highest precedence: options from the caller
GitHub.Repos.get("aj-foster", "open-api-github", some: :option)

# Medium precedence: options in the plugin definition
{MyPlugin, :my_function, some: :option}

# Lowest precedence: global configuration
config :oapi_github, MyPlugin, some: :option

Plugins should take care to document their available options and avoid naming collisions.