GithubAPI

Website |Wiki |RDocs

A Ruby client for the official GitHub API.

Supports all the API methods. It's built in a modular way. You can either instantiate the whole API wrapper Github.new or use parts of it i.e. Github::Client::Repos.new if working solely with repositories is your main concern. Intuitive query methods allow you easily call API endpoints.

Features

• Intuitive GitHub API interface navigation.
• It's comprehensive. You can request all GitHub API resources.
• Modular design allows for working with parts of API.
• Fully customizable including advanced middleware stack construction.
• Supports OAuth2 authorization.
• Flexible argument parsing. You can write expressive and natural queries.
• Requests pagination with convenient DSL and automatic options.
• Easy error handling split for client and server type errors.
• Supports multithreaded environment.
• Custom media type specification through the 'media' parameter.
• Request results caching
• Fully tested with unit and feature tests hitting the live api.

Installation

Install the gem by running

geminstallgithub_api

or put it in your Gemfile and runbundle install

gem"github_api"

Contents

• 1. Usage
  • 1.1 API Navigation
  • 1.2 Modularity
  • 1.3 Arguments
  • 1.4 Response Querying
    • 1.4.1 Response Body
    • 1.4.2 Response Headers
    • 1.4.3 Response Success
  • 1.5 Request Headers
    • 1.5.1 Media Types
• 2. Configuration
  • 2.1 Basic
  • 2.2 Advanced
  • 2.3 SSL
  • 2.4 Caching
• 3. Authentication
  • 3.1 Basic
  • 3.2 Authorizations API
  • 3.3 Scopes
  • 3.4 Application OAuth
  • 3.5 Two-Factor
• 4. Pagination
  • 4.1 Auto pagination
• 5. Error Handling
  • 5.1 Client Error
  • 5.2 Service Error
  • 5.2.1 Data
  • 5.2.2 Error Messages
• 6. Examples
  • 6.1 Rails
  • 6.2 Manipulating Files
• 7. Testing

1 Usage

To start using the gem, you can either perform requests directly onGithub namespace:

Github.repos.listuser:'piotrmurach'

or create a new client instance like so

github=Github.new

and then call api methods, for instance, to list a given user repositories do

github.repos.listuser:'piotrmurach'

1.1 API Navigation

Thegithub_api closely mirrors theGitHub API hierarchy. For example, if you want to create a new file in a repository, look up the GitHub API spec. In there you will find contents sub category underneath the repository category. This would translate to the request:

github=Github.newgithub.repos.contents.create'piotrmurach','finite_machine','hello.rb',path:'hello.rb',content:"puts 'hello ruby'"

The whole library reflects the same api navigation. Therefore, if you need to list releases for a repository do:

github.repos.releases.list'piotrmurach','finite_machine'

or to list a user's followers:

github.users.followers.list'piotrmurach'

The code base has been extensively documented with examples of how to use each method. Please refer to thedocumentation under theGithub::Client class name.

Alternatively, you can find out which methods are supported by an api by callingactions on a class or instance. For example, in order to find out available endpoints forGithub::Client::Repos::Contents api callactions method:

Github::Client::Repos::Contents.actions=> [:archive, :create, :delete, :find, :get, :readme, :update]

1.2 Modularity

The code base is modular. This means that you can work specifically with a given part of GitHub API. If you want to only work with activity starring API do the following:

starring=Github::Client::Activity::Starring.newoauth_token:tokenstarring.star'piotrmurach','github'

Please refer to thedocumentation and look underGithub::Client to see all available classes.

1.3 Arguments

Thegithub_api library allows for flexible argument parsing.

Arguments can be passed directly inside the method called. Therequired arguments are passed in first, followed by optional parameters supplied as hash options:

issues=Github::Client::Issues.newissues.milestones.list'piotrmurach','github',state:'open'

In the previous example, the order of arguments is important. However, each method also allows you to specifyrequired arguments using hash symbols and thus remove the need for ordering. Therefore, the same example could be rewritten like so:

issues=Github::Client::Issues.newissues.milestones.listuser:'piotrmurach',repo:'github',state:'open'

Furthermore,required arguments can be passed during instance creation:

issues=Github::Client::Issues.newuser:'piotrmurach',repo:'github'issues.milestones.liststate:'open'

Similarly, therequired arguments for the request can be passed inside the current scope such as:

issues=Github::Client::Issues.newissues.milestones(user:'piotrmurach',repo:'github').liststate:'open'

But why limit ourselves? You can mix and match arguments, for example:

issues=Github::Client::Issues.newuser:'piotrmurach'issues.milestones(repo:'github').listissues.milestones(repo:'tty').list

You can also use a bit of syntactic sugar whereby "username/repository" can be passed as well:

issues=Github::Client::Issues.newissues.milestones('piotrmurach/github').listissues.milestones.list'piotrmurach/github'

Finally, use thewith scope to clearly denote your requests

issues=Github::Client::Issues.newissues.milestones.with(user:'piotrmurach',repo:'github').list

Please consult the methoddocumentation orGitHub specification to see which arguments are required and what are the option parameters.

1.4 Response Querying

The response is of typeGithub::ResponseWrapper and allows traversing all the json response attributes like method calls. In addition, if the response returns more than one resource, these will be automatically yielded to the provided block one by one.

For example, when request is issued to list all the branches on a given repository, each branch will be yielded one by one:

repos=Github::Client::Repos.newrepos.branchesuser:'piotrmurach',repo:'github'do|branch|putsbranch.nameend

1.4.1 Response Body

TheResponseWrapper allows you to call json attributes directly as method calls. there is no magic here, all calls are delegated to the response body. Therefore, you can directly inspect request body by callingbody method on theResponseWrapper like so:

response=repos.branchesuser:'piotrmurach',repo:'github'response.body# => Array of branches

1.4.2 Response Headers

Each response comes packaged with methods allowing for inspection of HTTP start line and headers. For example, to check for rate limits and status codes do:

response=Github::Client::Repos.branches'piotrmurach','github'response.headers.ratelimit_limit# "5000"response.headers.ratelimit_remaining# "4999"response.headers.status# "200"response.headers.content_type# "application/json; charset=utf-8"response.headers.etag# "\"2c5dfc54b3fe498779ef3a9ada9a0af9\""response.headers.cache_control# "public, max-age=60, s-maxage=60"

1.4.3 Response Success

If you want to verify if the response was success, namely, that the200 code was returned call thesuccess? like so:

response=Github::Client::Repos.branches'piotrmurach','github'response.success?# => true

1.5 Request Headers

It is possible to specify additional header information which will be added to the final request.

For example, to setetag andX-Poll_Interval headers, use the:headers hash key inside the:options hash like in the following:

events=Github::Client::Activity::Events.newevents.publicheaders:{'X-Poll-Interval':60,'ETag':"a18c3bded88eb5dbb5c849a489412bf3"}

1.5.1 Media Types

In order to set custom media types for a request use the accept header. By using the:accept key you can determine media type like in the example:

issues=Github::Client::Issues.newissues.get'piotrmurach','github',108,accept:'application/vnd.github.raw'

2 Configuration

Thegithub_api provides ability to specify global configuration options. These options will be available to all api calls.

2.1 Basic

The configuration options can be set by using theconfigure helper

Github.configuredo|c|c.basic_auth="login:password"c.adapter=:typheousc.user='piotrmurach'c.repo='finite_machine'end

Alternatively, you can configure the settings by passing a block to an instance like:

Github.newdo|c|c.endpoint='https://github.company.com/api/v3'c.site='https://github.company.com'c.upload_endpoint='https://github.company.com/api/uploads'end

or simply by passing hash of options to an instance like so

github=Github.newbasic_auth:'login:password',adapter::typheous,user:'piotrmurach',repo:'finite_machine'

The following is the full list of available configuration options:

adapter# Http client used for performing requests. Default :net_httpauto_pagination# Automatically traverse requests page links. Default falsebasic_auth# Basic authentication in form login:password.client_id# Oauth client id.client_secret# Oauth client secret.connection_options# Hash of connection options.endpoint# Enterprise API endpoint. Default: 'https://api.github.com'oauth_token# Oauth authorization token.org# Global organization used in requests if none providedper_page# Number of items per page. Max of 100. Default 30.repo# Global repository used in requests in none providedsite# enterprise API web endpointssl# SSL settings in hash form.user# Global user used for requests if none provideduser_agent# Custom user agent name. Default 'Github API Ruby Gem'

2.2 Advanced

Thegithub_api will use the default middleware stack which is exposed by callingstack on a client instance. However, this stack can be freely modified with methods such asinsert,insert_after,delete andswap. For instance, to add yourCustomMiddleware do:

Github.configuredo|c|c.stack.insert_afterGithub::Response::Helpers,CustomMiddlewareend

Furthermore, you can build your entire custom stack and specify other connection options such asadapter by doing:

Github.newdo|c|c.adapter:exconc.stackdo|builder|builder.useGithub::Response::Helpersbuilder.useGithub::Response::Jsonizeendend

2.3 SSL

By default requests over SSL are set to OpenSSL::SSL::VERIFY_PEER. However, you can turn off peer verification by

github=Github.newssl:{verify:false}

If your client fails to find CA certs, you can pass other SSL options to specify exactly how the information is sourced

ssl: {  client_cert: "/usr/local/www.example.com/client_cert.pem"  client_key:  "/user/local/www.example.com/client_key.pem"  ca_file:     "example.com.cert"  ca_path:     "/etc/ssl/"}

For instance, download CA root certificates from Mozillacacert and point ca_file at your certificate bundle location. This will allow the client to verify the github.com ssl certificate as authentic.

2.4 Caching

Caching is supported through thefaraday-http-cache gem.

Add the gem to your Gemfile:

gem'faraday-http-cache'

You can now configure cache parameters as follows

Github.configuredo|config|config.stack=procdo|builder|builder.useFaraday::HttpCache,store:Rails.cacheendend

More details on the available options can be found in the gem's own documentation:https://github.com/plataformatec/faraday-http-cache#faraday-http-cache

3 Authentication

3.1 Basic

To start making requests as authenticated user you can use your GitHub username and password like so

Github.newbasic_auth:'login:password'

Though this method is convenient you should strongly consider usingOAuth for improved security reasons.

3.2 Authorizations API

3.2.1 For a User

To create an access token through the GitHub Authorizations API, you are required to pass your basic credentials and scopes you wish to have for the authentication token.

github=Github.newbasic_auth:'login:password'github.auth.createscopes:['repo'],note:'admin script'

You can add more than one scope from theuser,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).

3.2.2 For an App

Furthermore, to create auth token for an application you need to pass:app argument together with:client_id and:client_secret parameters.

github=Github.newbasic_auth:'login:password'github.auth.app.create'client-id',scopes:['repo']

In order to revoke auth token(s) for an application you must use basic authentication withclient_id as login andclient_secret as password.

github=Github.newbasic_auth:"client_id:client_secret"github.auth.app.delete'client-id'

Revoke a specific app token.

github.auth.app.delete'client-id','access-token'

3.3 Scopes

You can check OAuth scopes you have by:

github=Github.newoauth_token:'token'github.scopes.list# => ['repo']

or inidividually for a given user:

github=Github.newgithub.scopes.list'token'

To list the scopes that the particular GitHub API action checks for do:

repos=Github::Client::Repos.newresponse=repos.listuser:'piotrmurach'response.headers.accepted_oauth_scopes# => ['delete_repo', 'repo', 'public_repo']

To understand what each scope means refer todocumentation

3.4 Application OAuth

In order to authenticate your app through OAuth2 on GitHub you need to

• Visithttps://github.com/settings/applications/new and register your app.You will need to be logged in to initially register the application.

• Authorize your credentialshttps://github.com/login/oauth/authorize

You can use convenience methods to help you achieve this usingGithubAPI gem:

github=Github.newclient_id:'...',client_secret:'...'github.authorize_urlredirect_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.

Note: If you are working locally (i.e. your app URL and callback URL are localhost), do not specify a:redirect_uri otherwise you will get aredirect_uri_mismatch error.

3.5 Two-Factor

In order to useTwo-Factor authentication you need provideX-GitHub-OTP: required; :2fa-type header.

You can add headers during initialization:

Github.newdo|config|config.basic_auth="user:password"config.connection_options={headers:{"X-GitHub-OTP"=>'2fa token'}}end

or per request:

github=Github.newbasic_auth:'login:password'github.oauth.createscopes:["public_repo"],headers:{"X-GitHub-OTP"=>"2fa token"}

4 Pagination

Any request that returns multiple items will be paginated to 30 items by default. You can specify custompage andper_page query parameters to alter default behavior. For instance:

repos=Github::Client::Repos.newresponse=repos.listuser:'wycats',per_page:10,page:5

Then you can query the pagination information included in the link header by:

response.links.first# Shows the URL of the first page of results.response.links.next# Shows the URL of the immediate next page of results.response.links.prev# Shows the URL of the immediate previous page of results.response.links.last# Shows the URL of the last page of results.

In order to iterate through the entire result set page by page, you can use convenience methods:

response.each_pagedo|page|page.eachdo|repo|putsrepo.nameendend

or usehas_next_page? andnext_page helper methods like in the following:

while response.has_next_page?  ... process response ...  res.next_pageend

One can also navigate straight to the specific page by:

res.count_pages# Number of pagesres.page5# Requests given page if it exists, nil otherwiseres.first_page# Get first pageres.next_page# Get next pageres.prev_page# Get previous pageres.last_page# Get last page

4.1 Auto pagination

You can retrieve all pages in one invocation by passing theauto_pagination option like so:

github=Github.newauto_pagination:true

Depending at what stage you pass theauto_pagination it will affect all or only a single request. For example, in order to auto paginate all Repository API methods do:

Github::Сlient::Repos.newauto_pagination:true

However, to only auto paginate results for a single request do:

Github::Client::Repos.new.listuser:'...',auto_pagination:true

5 Error Handling

The generic error classGithub::Error::GithubError will handle both the client (Github::Error::ClientError) and service (Github::Error::ServiceError) side errors.

For instance in your code you can catch errors like

begin# Do something with github_api gemrescueGithub::Error::GithubError=>eputse.messageife.is_a?Github::Error::ServiceError# handle GitHub service errors such as 404elsife.is_a?Github::Error::ClientError# handle client errors e.i. missing required parameter in requestendend

5.1 Client Error

Any timeGithub client has a problem sending request aGithub::Error::ClientError is raised that will provide a summary of the problem and possible solutions.

5.2 Service Error

When theGithub client receives a HTTP response from GitHub service that indicates error thenGithub::Error::ServiceError is raised.

There are number of specific error types such asGithub::Error::NotAcceptable when406 status code is returned.

5.2.1 Data

WhenGithub::Error::ServiceError is raised you can calldata to access it payload in JSON format.

5.2.2 Error messages

Anytime there are error messages provided withGithub::Error::ServiceError you can access them by callingerror_messages helper.

6 Examples

6.1 Rails

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

classGithubController<ApplicationControllerdefauthorizeaddress=github.authorize_urlredirect_uri:'http://...',scope:'repo'redirect_toaddressenddefcallbackauthorization_code=params[:code]access_token=github.get_tokenauthorization_codeaccess_token.token# => returns token valueendprivatedefgithub@github||=Github.newclient_id:'...',client_secret:'...'endend

6.2 Manipulating Files

In order to be able to create/update/remove files you need to use Contents API like so:

contents=Github::Client::Repos::Contents.newoauth_token:'...'

Having instantiated the contents, to create a file do:

contents.create'username','repo_name','full_path_to/file.ext',path:'full_path_to/file.ext',message:'Your commit message',content:'The contents of your file'

Content is all Base64 encoded to/from the API, and when you create a file it encodes it automatically for you.

To update a file, first you need to find the file so you can get the SHA you're updating off of:

file=contents.findpath:'full_path_to/file.ext'

Then update the file just like you do with creating:

contents.update 'username', 'repo_name', 'full_path_to/file.ext',  path: 'full_path_to/file.ext'  message: 'Your commit message',  content: 'The contents to be updated',  sha: file.sha

Finally to remove a file, find the file so you can get the SHA you're removing:

file=contents.findpath:'full_path_to/file.ext'

Then delete the file like so:

github.delete'username','tome-of-knowledge','full_path_to/file.ext',path:'full_path_to/file.ext',message:'Your Commit Message',sha:file.sha

7 Testing

The test suite is split into two groups,live andmock.

Thelive tests are in thefeatures folder and exercise the GitHub API directly by making live requests and then caching responses with VCR in directory namedfeatures\cassettes. For details on how to get set up, please navigate to thefeatures folder.

To run all feature tests do:

bundleexecrakefeatures

Themock tests are in thespec folder and their primary concern is to test the gem internals without the hindrance of external calls.

To run all specs do:

bundleexecrakespec

Finally to run all tests do:

bundleexecrake

Development

Questions or problems? Please post them on theissue tracker. You can contribute changes by forking the project and submitting a pull request. You can ensure the tests are passing by runningbundle andrake.

Contributing

Bug reports and pull requests are welcome on GitHub athttps://github.com/piotrmurach/github. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to theContributor Covenant code of conduct.

Copyright

Copyright (c) 2011 Piotr Murach. See LICENSE.txt for further details.