{"name":"Github","body":"# GithubAPI\r\n[][travis] [][gemnasium]\r\n\r\n[travis]: http://travis-ci.org/peter-murach/github\r\n[gemnasium]: https://gemnasium.com/peter-murach/github\r\n\r\n[Wiki](https://github.com/peter-murach/github/wiki) | [RDocs](http://rubydoc.info/github/peter-murach/github/master/frames)\r\n\r\nA Ruby wrapper for the GitHub REST API v3.\r\n\r\nSupports 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.\r\n\r\n## Installation\r\n\r\nInstall the gem by issuing\r\n\r\n```ruby\r\ngem install github_api\r\n```\r\n\r\nor put it in your Gemfile and run `bundle install`</tt>\r\n\r\n```ruby\r\ngem \"github_api\"\r\n```\r\n\r\n## Usage\r\n\r\nCreate a new client instance\r\n\r\n```ruby\r\n@github = Github.new\r\n```\r\n\r\nAt 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\r\n\r\n```ruby\r\n@github = Github.new :user => 'peter-murach', :repo => 'github-api'\r\n```\r\n\r\nor\r\n\r\n```ruby\r\n@github = Github.new do |opts|\r\n opts.user = 'peter-murach'\r\n opts.repo = 'github-api'\r\nend\r\n```\r\n\r\nYou can authenticate either using OAuth authentication convenience methods(see section OAuth) or through basic authentication by passing your login and password credentials\r\n\r\n```ruby\r\n@github = Github.new :login => 'peter-murach', :password => '...'\r\n```\r\n\r\nor use convenience method:\r\n\r\n```ruby\r\n@github = Github.new :basic_auth => 'login:password'\r\n```\r\n\r\nYou can interact with GitHub interface, for example repositories, by issueing following calls\r\n\r\n```ruby\r\[email protected]\r\[email protected]\r\[email protected]\r\n```\r\n\r\nThe code base is modular and allows for you to work specifically with a given part of GitHub API e.g. repositories\r\n\r\n```ruby\r\n@repos = Github::Repos.new\r\[email protected] 'peter-murach', 'github'\r\n\r\nor\r\n\r\n@repos = Github::Repos.new :user => 'peter-murach', :repo => 'github'\r\[email protected]\r\n```\r\n\r\nThe response is of type [Hashie::Mash] and allows to traverse all the json response attributes like method calls e.i.\r\n\r\n```ruby\r\n@repos = Github::Repos.new :user => 'peter-murach', :repo => 'github'\r\[email protected] do |branch|\r\n puts branch.name\r\nend\r\n```\r\n\r\n## API\r\n\r\nMain API methods are grouped into the following classes that can be instantiated on their own\r\n\r\n```ruby\r\nGithub - full API access\r\nGithub::Gists\r\nGithub::GitData\r\nGithub::Issues\r\nGithub::Orgs\r\nGithub::PullRequests\r\nGithub::Repos\r\nGithub::Users\r\nGithub::Events\r\nGithub::Authorizations\r\n```\r\n\r\nSome parts of GitHub API v3 require you to be autheticated, for instance the following are examples of APIs only for the authenticated user\r\n\r\n```ruby\r\nGithub::Users::Emails\r\nGithub::Users::Keys\r\n```\r\n\r\nAll method calls form ruby like sentences and allow for intuitive api navigation, for instance\r\n\r\n```ruby\r\n@github = Github.new :oauth_token => '...'\r\[email protected] 'wycats' # => returns users that 'wycats' is following\r\[email protected] 'wycats' # => returns true if following, otherwise false\r\n```\r\n\r\nFor specification on all available methods go to http://developer.github.com/v3/ or\r\nread the rdoc, all methods are documented there with examples of usage. Alternatively,\r\nyou can find out supported methods by issuing the following in your `irb`:\r\n\r\n```ruby\r\n>> Github::Repos.actions\r\n---\r\n|--> branches\r\n|--> contribs\r\n|--> contributors\r\n|--> create_repo\r\n...\r\n```\r\n\r\n## Inputs\r\n\r\nSome API methods apart from required parameters such as username, repository name\r\nor organisation name, allow you to switch the way the data is returned to you, for instance\r\n\r\n```ruby\r\n@github = Github.new\r\[email protected]_data.tree 'peter-murach', 'github', 'c18647b75d72f19c1e0cc8af031e5d833b7f12ea'\r\n# => gets a tree\r\n\r\[email protected]_data.tree 'peter-murach', 'github', 'c18647b75d72f19c1e0cc8af031e5d833b7f12ea', :recursive => true\r\n# => gets a whole tree recursively\r\n```\r\n\r\nby passing a block you can iterate over the file tree\r\n\r\n```ruby\r\[email protected]_data.tree 'peter-murach', 'github', 'c18647b75d72f19c1e0cc8af031e5d833b7f12ea',\r\n :recursive => true do |file|\r\n\r\n puts file.path\r\nend\r\n```\r\n\r\n## OAuth\r\n\r\nIn order to authenticate the user through OAuth2 on GitHub you need to\r\n\r\n* visit https://github.com/settings/applications/new and register your app\r\n You will need to be logged in to initially register the application.\r\n\r\n* authorize your credentials https://github.com/login/oauth/authorize\r\n You can use convenience methods to help you achieve this that come with this gem:\r\n\r\n```ruby\r\n@github = Github.new :client_id => '...', :client_secret => '...'\r\[email protected]_url :redirect_uri => 'http://localhost', :scope => 'repo'\r\n# => \"https://github.com/login/oauth/authorize?scope=repo&response_type=code&client_id='...'&redirect_uri=http%3A%2F%2Flocalhost\"\r\n```\r\nAfter you get your authorization code, call to receive your access_token\r\n\r\n```ruby\r\ntoken = github.get_token( authorization_code )\r\n```\r\n\r\nOnce you have your access token, configure your github instance following instructions under Configuration.\r\n\r\nAlternatively you can use OAuth Authorizations API. For instance, to create access token through GitHub API do following\r\n\r\n```ruby\r\n@github = Github.new :basic_auth => 'login:password'\r\[email protected]_authorization 'scopes' => ['repo']\r\n```\r\n\r\nYou can add more than one scope from the <tt>user</tt>, <tt>public_repo</tt>, <tt>repo</tt>, <tt>gist</tt> 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).\r\n\r\n## MIME Types\r\n\r\nIssues, PullRequests and few other API leverage custom mime types which are <tt>:json</tt>, <tt>:blob</tt>, <tt>:raw</tt>, <tt>:text</tt>, <tt>:html</tt>, <tt>:full</tt>. By default <tt>:raw</tt> is used.\r\n\r\nIn order to pass a mime type with your request do\r\n\r\n```ruby\r\n@github = Github.new\r\[email protected]_requests.pull_requests 'peter-murach', 'github', :mime_type => :full\r\n```\r\n\r\n Your header will contain 'Accept: \"application/vnd.github-pull.full+json\"' which in turn returns raw, text and html representations in response body.\r\n\r\n## Configuration\r\n\r\nCertain methods require authentication. To get your GitHub OAuth v2 credentials,\r\nregister an app at https://github.com/settings/applications/\r\nYou will need to be logged in to register the application.\r\n\r\n```ruby\r\nGithub.configure do |config|\r\n config.oauth_token = YOUR_OAUTH_ACCESS_TOKEN\r\n config.basic_auth = 'login:password'\r\nend\r\n\r\nor\r\n\r\nGithub.new(:oauth_token => YOUR_OAUTH_TOKEN)\r\nGithub.new(:basic_auth => 'login:password')\r\n```\r\n\r\nAll parameters can be overwirtten as per method call. By passing parameters hash...\r\n\r\n## Caching\r\n\r\nEach `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.\r\n\r\n Github.cache do...\r\n\r\n## Pagination\r\n\r\nAny request that returns multiple items will be paginated to 30 items by default. You can specify custom <tt>:page</tt> and <tt>:per_page</tt> query parameters to alter default behavior. For instance:\r\n\r\n```ruby\r\nres = Github::Repos.new.repos :user => 'wycats', :per_page => 10\r\n```\r\n\r\nThen you can query pagination information included in the link header by:\r\n\r\n```ruby\r\nres.links.first # Shows the URL of the first page of results.\r\nres.links.next # Shows the URL of the immediate next page of results.\r\nres.links.prev # Shows the URL of the immediate previous page of results.\r\nres.links.last # Shows the URL of the last page of results.\r\n```\r\n\r\nIn order to iterate through the entire result set page by page, you can use convenience methods:\r\n\r\n```ruby\r\nres.each_page do |page|\r\n page.each do |repo|\r\n puts repo.name\r\n end\r\nend\r\n```\r\n\r\nor use `has_next_page?` and `next_page` like in the following:\r\n\r\n```ruby\r\nwhile res.has_next_page?\r\n ... process response ...\r\n res.next_page\r\nend\r\n```\r\n\r\nOne can also navigate straight to specific page by:\r\n\r\n```ruby\r\nres.page 5 # Requests given page if it exists, nil otherwise\r\nres.first_page\r\nres.prev_page\r\nres.last_page\r\n```\r\n\r\n## Response Message\r\n\r\nEach response comes packaged with methods allowing for inspection of HTTP start line and headers. For example to check for rate limits and status code issue\r\n\r\n```ruby\r\nres = Github::Repos.new.branches 'peter-murach', 'github'\r\nres.ratelimit_limit # \"5000\"\r\nres.ratelimit_remainig # \"4999\"\r\nres.status # \"200\"\r\nres.content_type # \"application/json; charset=utf-8\"\r\n```\r\n\r\n## Examples\r\n\r\nSome api methods require input parameters, these are added simply as a hash properties, for instance\r\n\r\n```ruby\r\n@issues = Github::Issues.new :user => 'peter-murach', :repo => 'github-api'\r\[email protected] :state => 'open', :sort => 'due_date', :direction => 'asc'\r\n```\r\n\r\nOther methods may require inputs as an array of strings\r\n\r\n```ruby\r\n@users = Github::Users.new :oauth_token => '...'\r\[email protected]_email 'email1', 'email2', ..., 'emailn' # => Adds emails to the authenticated user\r\n```\r\n\r\nIf a method returns a collection, you can iterator over it by supplying a block parameter,\r\n\r\n```ruby\r\n@issues = Github::Issues.new :user => 'peter-murach', :repo => 'github-api'\r\[email protected] do |event|\r\n puts event.actor.login\r\nend\r\n```\r\n\r\nQuery requests instead of http responses return boolean values\r\n\r\n```ruby\r\n@github = Github.new\r\[email protected]_member? 'github', 'technoweenie' # => true\r\n```\r\n\r\n## Rails Example\r\n\r\nA Rails controller that allows a user to authorize their GitHub account and then perform request.\r\n\r\n```ruby\r\nclass GithubController < ApplicationController\r\n\r\n def authorize\r\n github = Github.new :client_id => '...', :client_secret => '...'\r\n address = github.authorize_url :redirect_uri => 'http://...', :scope => 'repo'\r\n redirect_to address\r\n end\r\n\r\n def callback\r\n authorization_code = params[:code]\r\n token = github.get_token authorization_code\r\n access_token = token.token\r\n end\r\nend\r\n```\r\n\r\n## TODO\r\n\r\n* Add request caching - local filestore?, http caching?.\r\n* Add live api tests\r\n\r\n## Development\r\n\r\nQuestions or problems? Please post them on the [issue tracker](https://github.com/peter-murach/github/issues). You can contribute changes by forking the project and submitting a pull request. You can ensure the tests are passing by running `bundle` and `rake`.\r\n\r\n## Copyright\r\n\r\nCopyright (c) 2011-2012 Piotr Murach. See LICENSE.txt for further details.\r\n","tagline":"Ruby interface to github API v3","google":"","note":"Don't delete this file! It's used internally to help with page regeneration."}