Nit wrapper for Github API

This module provides a Nit object oriented interface to access the Github api.

Accessing the API

GithubAPIClient to Github API

To access the API you need an instance of a GithubAPI client.

var token = get_github_oauth
assert not token.is_empty

# Init the client.
var api = new GithubAPI(token)

The API client allows you to get Github API entities.

var repo = api.load_repo("nitlang/nit")
assert repo != null
assert repo.name == "nit"

var user = api.load_user("Morriar")
assert user != null
assert user.login == "Morriar"

Authentification

authOAuth token

Use an empty string to disable authentication and connect anonymously (thus less capabilities and more rate limits)

Token can also be recovered from user config with `get_github_oauth`.

get_github_oauthGets the Github token from git configuration

Return the value of git config --get github.oauthtoken or "" if no key exists.

Retrieving user data

load_userGet the Github user with login

Loads the User from the API or returns null if the user cannot be found.

var api = new GithubAPI(get_github_oauth)
var user = api.load_user("Morriar")
print user or else "null"
assert user.login == "Morriar"

UserA Github user

Provides access to Github user data. Should be accessed from GithubAPI::load_user.

  • login: Github login.
  • login=: Github login.
  • avatar_url: Avatar image url for this user.
  • avatar_url=: Avatar image url for this user.
  • name: User public name if any.
  • name=: User public name if any.
  • email: User public email if any.
  • email=: User public email if any.
  • blog: User public blog if any.
  • blog=: User public blog if any.

Retrieving repo data

load_repoGet the Github repo with full_name.

Loads the Repo from the API or returns null if the repo cannot be found.

var api = new GithubAPI(get_github_oauth)
var repo = api.load_repo("nitlang/nit")
assert repo.name == "nit"
assert repo.owner.login == "nitlang"
assert repo.default_branch == "master"

RepoA Github repository.

Provides access to Github repo data. Should be accessed from GithubAPI::load_repo.

Other data

Advanced uses

Caching

cacheEnable caching on Github API accesses.

If GithubAPI::enable_cache is set to true then Github JSON responses will be cached locally using JsonStore.

Cache can be used to limit the number of access on the API and lighten the rate limit on your github key.

Usage:

var api = new GithubAPI(get_github_oauth)
api.enable_cache = true

var name = "nitlang/nit"
assert not api.has_cache(name)
var repo = api.load_repo(name) # load from GitHub
#assert api.has_cache(name) FIXME bring back this assert
repo = api.load_repo(name) # load from cache

api.clear_cache
assert not api.has_cache(name)

Custom requests

getExecute a GET request on Github API.

This method returns raw json data. See other load_* methods to use more expressive types.

var api = new GithubAPI(get_github_oauth)
var obj = api.get("/repos/nitlang/nit")
assert obj isa JsonObject
assert obj["name"] == "nit"

Returns null in case of error.

obj = api.get("/foo/bar/baz")
assert obj == null
assert api.was_error
var err = api.last_error
assert err isa GithubError
assert err.name == "GithubAPIError"
assert err.message == "Not Found"

Change the user agent

Debugging

verbose_lvlVerbosity level.

  • 0: only errors (default)
  • 1: verbose

Using with GitLab

If URL scheme of GitLab API follows the one of Github API, it may be possible to configure this wrapper to use a custom URL.
api_urlGithub API base url.

Default is https://api.github.com and should not be changed.

Creating hooks

Using this API you can create Github hooks able to respond to actions performed on a repository.

hooksGithub hook event listening with nitcorn.

Usage:

import github::hooks

# A simple hook listener that print received events in stdout.
class LogHookListener
   super HookListener

   # Use double dispatch to implement log behavior.
   redef fun apply_event(event) do event.log_event(self)
end

redef class GithubEvent
   # Log this event.
   #
   # Do nothing by default.
   fun log_event(l: LogHookListener) do end
end

redef class CommitCommentEvent

   redef fun log_event(l) do
       print "new comment on commit {comment.commit_id}"
   end
end

var api = new GithubAPI(get_github_oauth)
var listener = new LogHookListener(api, "127.0.0.1", 8080)

Dealing with events

GithubAPI can trigger different events depending on the hook configuration.