Skip to content

Latest commit

 

History

History
116 lines (80 loc) · 4.62 KB

README.md

File metadata and controls

116 lines (80 loc) · 4.62 KB
Raw

GitHub REST API Client for Elixir

Hex.pm Documentation Contributor Covenant

The ergonomics of a hand-crafted client with the API coverage of generated code.

This library uses an OpenAPI Code Generator that has the flexibility to wrangle the generated code into an ergonomic client. So instead of dealing with NullableRepository vs. FullRepository and other odd artifacts of GitHub's OpenAPI description, there's a predictable interface.

Furthermore, this library has no opinions about what you use for HTTP requests, serialization, etc. Instead it allows users to define their own stack of plugins, many of which are provided here.

Installation

This library is available on Hex.pm. Add the dependency in mix.exs:

def deps do
  [
    {:oapi_github, "~> 0.3.3"}
  ]
end

Then install the dependency using mix deps.get.

Configuration

This library comes with a common default set of configuration. To use it successfully, you will need to install HTTPoison and Jason. (Remember, these libraries can easily be switched out by changing the stack configuration. See GitHub.Config for more information.)

Some good up-and-running configuration to set:

  • app_name will include the name of your application in the User Agent so GitHub can contact you if they notice any problems.
  • default_auth allows you to provide default Authorization header credentials, such as a client ID and secret to increase your rate limit when no other credentials are available.
config :oapi_github,
  app_name: "MyApp",
  default_auth: {"client_id", "client_secret"}

For more information about configuration, see the documentation for GitHub.Config.

Usage

All of the client operations are generated based on the OpenAPI description provided by GitHub. In general, you can expect to find:

GitHub.Resource.operation(path1, path2, ..., body, opts)

Where:

  • Resource is the name of the resource as tagged by GitHub, like Repos.
  • operation is the name of the route, like get or create_commit_comment.
  • The first arguments are path parameters, such as owner and repo in /repos/{owner}/{repo}.
  • If the request accepts a body, then there will be a body parameter.
  • Finally, all operations accept a keyword list of options.

The options accepted by operations may differ depending on your chosen stack. However, the following are always available:

  • auth (string, 2-tuple, or struct implementing GitHub.Auth) Credentials to use for the request.
  • server (URL including scheme) Base API server to use, such as https://api.github.com (useful for interacting with GitHub Enterprise installations).
  • version (string) GitHub API version to use (not recommended to override this, because the generated code may not match the specified version).

Whenever GitHub specifies a named schema as the response type for an operation, an Elixir struct will be returned. Note that GitHub often has similarly named schemas (such as SimpleUser, PrivateUser, PublicUser, etc.). Where possible, these have been collapsed into a single struct (like GitHub.User) where not all of the fields may be filled in. However, responses are still properly typed by their type specifications.

Testing

Test helpers are available in GitHub.Testing together with the GitHub.Plugins.TestClient plugin.

defmodule MyApp.MyTest do
  use ExUnit.Case
  use GitHub.Testing

  test "calls GitHub API" do
    mock_gh &GitHub.Repo.get/2, fn ->
      {:ok, 200, %GitHub.Repository{id: 12345}}
    end

    my_function()

    assert_called_gh GitHub.Repos.get("owner", :_)
  end
end

For more information, see the documentation for GitHub.Testing.

Contributing

Because this library uses a code generator for the majority of its mass, there are two modes of contribution. Please consider these when creating issues or opening pull requests:

  • If the generated code is out of date, the fix may be as simple as running mix gen.api using the latest OpenAPI description.
  • If the client isn't working as expected, the fix may be more involved and require careful thought and versioning.

For more on what this means to you as a contributor, please see the contribution guidelines.

Sponsorship

If you like this library or it makes you money, please consider sponsoring.