<commit_before># GithubAPI

[![Gem Version](https://badge.fury.io/rb/github_api.png)](http://badge.fury.io/rb/github_api) [![Build Status](https://secure.travis-ci.org/peter-murach/github.png?branch=master)][travis] [![Dependency Status](https://gemnasium.com/peter-murach/github.png?travis)][gemnasium] [![Code Climate](https://codeclimate.com/badge.png)][codeclimate] [![Coverage Status](https://coveralls.io/repos/peter-murach/github/badge.png?branch=master)][coveralls]

[travis]: http://travis-ci.org/peter-murach/github
[gemnasium]: https://gemnasium.com/peter-murach/github
[codeclimate]: https://codeclimate.com/github/peter-murach/github
[coveralls]: https://coveralls.io/r/peter-murach/github

[Wiki](https://github.com/peter-murach/github/wiki) | [RDocs](http://rubydoc.info/github/peter-murach/github/master/frames)

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.

## Features

* Intuitive GitHub API interface navigation. [usage](#usage)
* Modular design allows for working with parts of API. [api](#api)
* Fully customizable including advanced middleware stack construction. [config](#advanced-configuration)
* Its comprehensive, you can request all GitHub API resources.
* Support OAuth2 authorization. [oauth](#oauth)
* Flexible arguments parsing, you can write expressive and natural queries. [params]()
* Requests pagination with convenient DSL and automatic option. [pagination](#pagination)
* Easy error handling split for client and server type errors. [error](#error-handling)
* Supports multithreaded environment.
* Custom media types specification through 'media' parameter. [media](#media-types)
* Request results caching (Status: TODO)
* Fully tested with test coverage above 90% with over 1,600 specs and 900 features. [testing](#testing)

## Installation

Install the gem by issuing

```ruby
gem install github_api
```

or put it in your Gemfile and run `bundle install`

```ruby
gem "github_api"
```

## Usage

To start using the gem you can either perform direct call on the `Github`

```ruby
Github.repos.list user: 'wycats'
```

or create a new client instance

```ruby
github = Github.new
```

At this stage you can also supply various configuration parameters, such as
```
  adapter          # http client used for performing requests
  auto_pagination  # by default false, set to true traverses requests page links
  oauth_token      # oauth authorization token
  basic_auth       # login:password string
  client_id        # oauth client id
  client_secret    # oauth client secret
  user             # global user used in requets if none provided
  repo             # global repository used in requests in none provided
  org              # global organization used in request if none provided
  endpoint         # enterprise api endpoint
  site             # enterprise api web endpoint
  ssl              # ssl settings
  per_page         # number of items per page, max 100
  user_agent       # custom user agent name, by default 'Github API'
```
which are used throughout the API. These can be passed directly as hash options:

```ruby
github = Github.new oauth_token: 'token'
```

Alternatively, you can configure the Github settings by passing a block, for instance, with custom enterprise endpoint and website like

```ruby
github = Github.new do |config|
  config.endpoint    = 'https://github.company.com/api/v3'
  config.site        = 'https://github.company.com'
  config.oauth_token = 'token'
  config.adapter     = :net_http
  config.ssl         = {:verify => false}
end
```

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

```ruby
github = Github.new login:'peter-murach', password:'...'
```

or use convenience method:

```ruby
github = Github.new basic_auth: 'login:password'
```

This gem closely mirros the GitHub Api hierarchy e.i. if you want to create a download resource,
lookup the github api spec and issue the request as in `github.repos.downloads.create`

For example to interact with GitHub Repositories API, issue the following calls that correspond directly to the GitHub API hierarchy

```ruby
github.repos.commits.all  'user-name', 'repo-name'
github.repos.hooks.create 'user-name', 'repo-name', name: "web", active: true
github.repos.keys.get     'user-name', 'repo-name'
```

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

```ruby
blobs = Github::GitData::Blobs.new
blobs.create 'peter-murach', 'github', content: 'Blob content'
```

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

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

## Arguments & Parameters

The library allows for flexible arguments parsing. Therefore arguments can be passed during instance creation:

```ruby
  issues = Github::Issues.new user: 'peter-murach', repo: 'github'
  issues.milestones.list state: 'open'
```

Further, arguments can be passed directly inside method called but then the order of parameters matters and hence please consult the method documentation or GitHub specification. For instance:

```ruby
  issues = Github::Issues.new
  issues.milestones.list 'peter-murach', 'github', state: 'open'
```
<commit_msg>Update readme with correct response type.<commit_after># GithubAPI

[![Gem Version](https://badge.fury.io/rb/github_api.png)](http://badge.fury.io/rb/github_api) [![Build Status](https://secure.travis-ci.org/peter-murach/github.png?branch=master)][travis] [![Dependency Status](https://gemnasium.com/peter-murach/github.png?travis)][gemnasium] [![Code Climate](https://codeclimate.com/badge.png)][codeclimate] [![Coverage Status](https://coveralls.io/repos/peter-murach/github/badge.png?branch=master)][coveralls]

[travis]: http://travis-ci.org/peter-murach/github
[gemnasium]: https://gemnasium.com/peter-murach/github
[codeclimate]: https://codeclimate.com/github/peter-murach/github
[coveralls]: https://coveralls.io/r/peter-murach/github

[Wiki](https://github.com/peter-murach/github/wiki) | [RDocs](http://rubydoc.info/github/peter-murach/github/master/frames)

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.

## Features

* Intuitive GitHub API interface navigation. [usage](#usage)
* Modular design allows for working with parts of API. [api](#api)
* Fully customizable including advanced middleware stack construction. [config](#advanced-configuration)
* Its comprehensive, you can request all GitHub API resources.
* Support OAuth2 authorization. [oauth](#oauth)
* Flexible arguments parsing, you can write expressive and natural queries. [params]()
* Requests pagination with convenient DSL and automatic option. [pagination](#pagination)
* Easy error handling split for client and server type errors. [error](#error-handling)
* Supports multithreaded environment.
* Custom media types specification through 'media' parameter. [media](#media-types)
* Request results caching (Status: TODO)
* Fully tested with test coverage above 90% with over 1,600 specs and 900 features. [testing](#testing)

## Installation

Install the gem by issuing

```ruby
gem install github_api
```

or put it in your Gemfile and run `bundle install`

```ruby
gem "github_api"
```

## Usage

To start using the gem you can either perform direct call on the `Github`

```ruby
Github.repos.list user: 'wycats'
```

or create a new client instance

```ruby
github = Github.new
```

At this stage you can also supply various configuration parameters, such as
```
  adapter          # http client used for performing requests
  auto_pagination  # by default false, set to true traverses requests page links
  oauth_token      # oauth authorization token
  basic_auth       # login:password string
  client_id        # oauth client id
  client_secret    # oauth client secret
  user             # global user used in requets if none provided
  repo             # global repository used in requests in none provided
  org              # global organization used in request if none provided
  endpoint         # enterprise api endpoint
  site             # enterprise api web endpoint
  ssl              # ssl settings
  per_page         # number of items per page, max 100
  user_agent       # custom user agent name, by default 'Github API'
```
which are used throughout the API. These can be passed directly as hash options:

```ruby
github = Github.new oauth_token: 'token'
```

Alternatively, you can configure the Github settings by passing a block, for instance, with custom enterprise endpoint and website like

```ruby
github = Github.new do |config|
  config.endpoint    = 'https://github.company.com/api/v3'
  config.site        = 'https://github.company.com'
  config.oauth_token = 'token'
  config.adapter     = :net_http
  config.ssl         = {:verify => false}
end
```

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

```ruby
github = Github.new login:'peter-murach', password:'...'
```

or use convenience method:

```ruby
github = Github.new basic_auth: 'login:password'
```

This gem closely mirros the GitHub Api hierarchy e.i. if you want to create a download resource,
lookup the github api spec and issue the request as in `github.repos.downloads.create`

For example to interact with GitHub Repositories API, issue the following calls that correspond directly to the GitHub API hierarchy

```ruby
github.repos.commits.all  'user-name', 'repo-name'
github.repos.hooks.create 'user-name', 'repo-name', name: "web", active: true
github.repos.keys.get     'user-name', 'repo-name'
```

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

```ruby
blobs = Github::GitData::Blobs.new
blobs.create 'peter-murach', 'github', content: 'Blob content'
```

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

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

## Arguments & Parameters

The library allows for flexible arguments parsing. Therefore arguments can be passed during instance creation:

```ruby
  issues = Github::Issues.new user: 'peter-murach', repo: 'github'
  issues.milestones.list state: 'open'
```

Further, arguments can be passed directly inside method called but then the order of parameters matters and hence please consult the method documentation or GitHub specification. For instance:

```ruby
  issues = Github::Issues.new
  issues.milestones.list 'peter-murach', 'github', state: 'open'
```

{'fraction_non_alphanumeric': 0.10431178908385504, 'fraction_numerical': 0.00317432325191782, 'mean_word_length': 4.292580494633691, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 9, 'https://': 22, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 4, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6355935', 'n_tokens_mistral': 3433, 'n_tokens_neox': 3188, 'n_words': 1209}