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.

Grab the gem by issuing

gem install github-api

or in your Gemfile

gem 'github-api'

Create a new client instance

@github = Github.new

At this stage you can also supply various configuration parameters, such as :user, :repo, :org etc.., which are used thoughtout the API

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

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

• get your token github.com/login/oauth/access_token

Once you have your consumer and token keys, configure your github instance following instructions under Configuration.

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'

or

@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

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

Some parts of GitHub API v3 require you to be autheticated, for instance the following are examples of API 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.

Provides support for the following mime types

In order to pass a mime type with your request do

@github = Github.new :oauth_token
@github...

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
end

or

Github.new(:oauth_token => YOUR_OAUTH_TOKEN)

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

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

• Add support for mime types

• Add request caching - local filestore?, http caching?.

• Add oauth2 helper methods.

• Add response processing methods

• Add helper methods to return iterators over most common collections.

• Add response set helper methods e.i. pagination.

• Add DSL falvoured api access

• 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.

Copyright © 2011 Piotr Murach. See LICENSE.txt for further details.