Tentacat Documentation

If you do not provide a client struct, Tentacat will perform unauthenticated requests. Note that this limits the available API actions. When not using a client, call the module functions directly without passing a client argument as the first parameter.

# Unauthenticated call
Tentacat.Users.find("edgurgel")

To use GitHub API endpoints that are currently in a 'preview' state, you must include specific media type headers in your requests. You can set this globally in your configuration using the :extra_headers key.

config :tentacat,
  extra_headers: [{"Accept", "application/vnd.github.MEDIA-TYPE+json"}]

To use Tentacat in your Elixir project, add it to your mix.exs dependencies.

def deps do
  [
    {:tentacat, "~> 2.0"}
  ]
end

After adding the dependency, run mix deps.get to fetch it.

A %Tentacat.Client{} struct holds the endpoint information and authentication credentials. You can initialize it using several methods depending on your security requirements.

# Using a personal access token (Recommended)
client = Tentacat.Client.new(%{access_token: "YOUR_TOKEN"})

# Using username and password (May not work with MFA)
client = Tentacat.Client.new(%{user: "user", password: "password"})

# Connecting to an alternative endpoint (e.g., GitHub Enterprise)
client = Tentacat.Client.new(%{access_token: "TOKEN"}, "https://ghe.example.com/api/v3/")

Tentacat allows you to pass options to the underlying JSON decoder (Jason). For example, to have JSON keys returned as Atoms instead of Strings, configure the :deserialization_options key in your application configuration.

config :tentacat, :deserialization_options, [keys: :atoms]

You can configure global settings for Tentacat using the application environment. This is useful for setting default headers, pagination methods, or JSON decoding options.

config :tentacat,
  deserialization_options: [],
  extra_headers: [],
  pagination: [],
  request_options: []

The GitHub Reviews API is currently in a pre-release state. To use it, you must configure the extra_headers option in your application configuration to include the required Accept header.

config :tentacat, :extra_headers, [{"Accept", "application/vnd.github.black-cat-preview+json"}]

Once a client is created, pass it as the first argument to most Tentacat module functions to perform authenticated requests.

# Get a user's profile information
Tentacat.Users.find(client, "edgurgel")

# Create a comment on an issue
Tentacat.Issues.Comments.create("edgurgel", "tentacat", 72, %{"body" => "This is a comment created using the API"})

You can retrieve information about a specific GitHub user using Tentacat.Users.find/2 (requires a client) or Tentacat.Users.find/1 (unauthenticated).

Using a Client

client = Tentacat.Client.new()
{status, data, response} = Tentacat.Users.find(client, "username")

Unauthenticated (No Client)

{status, data, response} = Tentacat.Users.find("username")

Returns a tuple containing the HTTP status code, the decoded JSON body, and the full %HTTPoison.Response{} struct.

# Using a client
client = Tentacat.Client.new()
{200, data, _response} = Tentacat.Users.find(client, "edgurgel")

# Without a client
{200, data, _response} = Tentacat.Users.find("edgurgel")

Use Tentacat.Gists to retrieve lists of gists from various scopes:

• list_mine(client, params \ [], options \ []): Lists the current authenticated user's gists.
• list_users(client, owner, params \ [], options \ []): Lists gists belonging to a specific user (owner).
• list_public(client, params \ [], options \ []): Lists all public gists. Note: This method defaults to pagination: :none in its options.
• list_starred(client, params \ [], options \ []): Lists the authenticated user's starred gists. Note: This method defaults to pagination: :none in its options.

# List current user's gists
Tentacat.Gists.list_mine(client)

# List gists for a specific user
Tentacat.Gists.list_users(client, "steve")

# List all public gists
Tentacat.Gists.list_public(client)

# List starred gists
Tentacat.Gists.list_starred(client)

Use Tentacat.Commits.Comments.update/5 to modify an existing commit comment. The body argument should be a map containing the fields to update (e.g., "body").

Tentacat.Commits.Comments.update(client, "owner", "repo", comment_id, %{"body" => "updated text"})