GithubAPI <img src=“http://travis-ci.org/peter-murach/github.png?branch=master” /> <img src=“https://gemnasium.com/peter-murach/github.png?travis” />¶ ↑

A Ruby wrapper for the GitHub REST API v3.

Supports all the API methods(nearly 200). It’s build in a modular way, that is, you can either instantiate the whole api wrapper Github.new or use parts of it e.i. Github::Repos.new if working solely with repositories is your main concern.

Installation¶ ↑

Grab the gem by issuing

gem install github_api

or in your Gemfile

gem "github_api"

Usage¶ ↑

Create a new client instance

@github = Github.new

At this stage you can also supply various configuration parameters, such as :user, :repo, :org, :oauth_token, :login, :password or :basic_auth which are used throughout the API

@github = Github.new :user => 'peter-murach', :repo => 'github-api'

You can authenticate either using OAuth authentication convenience methods(see section OAuth) or through basic authentication by passing your login and password credentials

@github = Github.new :login => 'peter-murach', :password => '...'

or use convenience method:

@github = Github.new :basic_auth => 'login:password'

You can interact with GitHub interface, for example repositories, by issueing following calls

@github.repos.commits
@github.repos.branches
@github.repos.contributors

The code base is modular and allows for you to work specifically with a given part of GitHub API e.g. repositories

@repos = Github::Repos.new
@repos.branches 'peter-murach', 'github'

@repos = Github::Repos.new :user => 'peter-murach', :repo => 'github'
@repos.branches

The response is of type [Hashie::Mash] and allows to traverse all the json response attributes like method calls e.i.

@repos = Github::Repos.new :user => 'peter-murach', :repo => 'github'
@repos.branches do |branch|
  puts branch.name
end

API¶ ↑

Main API methods are grouped into the following classes that can be instantiated on their own

Github         - full API access
Github::Gists
Github::GitData
Github::Issues
Github::Orgs
Github::PullRequests
Github::Repos
Github::Users
Github::Events
Github::Authorizations

Some parts of GitHub API v3 require you to be autheticated, for instance the following are examples of APIs only for the authenticated user

Github::Users::Emails
Github::Users::Keys

All method calls form ruby like sentences and allow for intuitive api navigation, for instance

@github = Github.new :oauth_token => '...'
@github.users.following 'wycats'  # => returns users that 'wycats' is following
@github.users.following 'wycats' # => returns true if following, otherwise false

For specification on all available methods go to developer.github.com/v3/ or read the rdoc, all methods are documented there with examples of usage.

Inputs¶ ↑

Some API methods apart from required parameters such as username, repository name or organisation name, allow you to switch the way the data is returned to you, for instance

@github = Github.new
@github.git_data.tree 'peter-murach', 'github', 'c18647b75d72f19c1e0cc8af031e5d833b7f12ea' # => gets a tree

@github.git_data.tree 'peter-murach', 'github', 'c18647b75d72f19c1e0cc8af031e5d833b7f12ea', :recursive => true # => gets a whole tree recursively

by passing a block you can iterate over the file tree

@github.git_data.tree 'peter-murach', 'github', 'c18647b75d72f19c1e0cc8af031e5d833b7f12ea', :recursive => true do |file|
  puts file.path
end

OAuth¶ ↑

In order to authenticate the user through OAuth2 on GitHub you need to

visit github.com/account/applications/ and register your app

authorize your credentials github.com/login/oauth/authorize You can use convenience methods to help you achieve this that come with this gem:

@github = Github.new :client_id => '...', :client_secret => '...'
@github.authorize_url :redirect_uri => 'http://localhost', :scope => 'repo'
# => "https://github.com/login/oauth/authorize?scope=repo&response_type=code&client_id='...'&redirect_uri=http%3A%2F%2Flocalhost"

After you get your authorization code, call to receive your access_token

token = github.get_token( authorization_code )

Once you have your access token, configure your github instance following instructions under Configuration.

Alternatively you can use OAuth Authorizations API. For instance, to create access token through GitHub API do following

@github = Github.new :basic_auth => 'login:password'
@github.oauth.create_authorization 'scopes' => ['repo']

You can add more than one scope from the user, public_repo, repo, gist or leave the scopes parameter out, in which case, the default read-only access will be assumed(includes public user profile info, public repo info, and gists).

MIME Types¶ ↑

Issues, PullRequests and few other API leverage custom mime types which are :json, :blob, :raw, :text, :html, :full. By default :raw is used.

In order to pass a mime type with your request do

@github = Github.new
@github.pull_requests.pull_requests 'peter-murach', 'github', :mime_type => :full

Your header will contain 'Accept: "application/vnd.github-pull.full+json"' which in turn returns raw, text and html representations in response body.

Configuration¶ ↑

Certain methods require authentication. To get your GitHub OAuth v2 credentials, register an app at github.com/account/applications/

Github.configure do |config|
  config.oauth_token   = YOUR_OAUTH_ACCESS_TOKEN
  config.basic_auth    = 'login:password'
end

Github.new(:oauth_token => YOUR_OAUTH_TOKEN)
Github.new(:basic_auth => 'login:password)

All parameters can be overwirtten as per method call. By passing parameters hash…

Caching¶ ↑

Each get request by default is not going to be cached. In order to set the cache do… If no cache type is provided a default memoization is done.

Github.cache do...

Examples¶ ↑

Some api methods require input parameters, these are added simply as a hash properties, for instance

@issues = Github::Issues.new :user => 'peter-murach', :repo => 'github-api'
@issues.milestones :state => 'open', :sort => 'due_date', :direction => 'asc'

Other methods may require inputs as an array of strings

@users = Github::Users.new :oauth_token => '...'
@users.add_email 'email1', 'email2', ..., 'emailn' # => Adds emails to the authenticated user

If a method returns a collection, you can iterator over it by supplying a block parameter,

@issues = Github::Issues.new :user => 'peter-murach', :repo => 'github-api'
@issues.events do |event|
  puts event.actor.login
end

Query requests instead of http responses return boolean values

@github = Github.new
@github.orgs.public_member? 'github', 'technoweenie' # => true

Rails Example¶ ↑

A Rails controller that allows a user to authorize their GitHub account and then perform request.

class GithubController < ApplicationController

  def authorize
    github = Github.new :client_id => '...', :client_secret => '...'
    address = github.authorize_url :redirect_uri => 'http://...', :scope => 'repo'
    redirect_to address
  end

  def callback
    authorization_code = params[:code]
    token = github.get_token authorization_code
    access_token = token.token
  end
end

TODO¶ ↑

Add request caching - local filestore?, http caching?.
Add response processing methods
Add response set helper methods e.i. pagination.
Add DSL falvoured api access

Contributing to github¶ ↑

Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

reedlaw / github