github_api 0.10.2 → 0.11.0

data/README.md

@@ -1,36 +1,41 @@
 # 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]
+[![Gem Version](https://badge.fury.io/rb/github_api.png)][gem]
+[![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/github/peter-murach/github.png)][codeclimate]
+[![Coverage Status](https://coveralls.io/repos/peter-murach/github/badge.png?branch=master)][coveralls]
 
+[gem]: http://badge.fury.io/rb/github_api
 [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)
+[Website](http://peter-murach.github.io/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.
+Supports all the API methods (nearly 200). 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::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)
+* It's comprehensive. You can request all GitHub API resources.
+* Supports OAuth2 authorization. [oauth](#oauth)
+* Flexible argument parsing. You can write expressive and natural queries. [params](#arguments--parameters)
+* Requests pagination with convenient DSL and automatic options. [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)
+* Custom media type specification through the '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)
+* Fully tested with test coverage above 90% with over 1,600 specs and 1000 features. [testing](#testing)
 
 ## Installation
 
-Install the gem by issuing
+Install the gem by running
 
 ```ruby
 gem install github_api
@@ -44,7 +49,7 @@ gem "github_api"
 
 ## Usage
 
-To start using the gem you can either perform direct call on the `Github`
+To start using the gem, you can either perform direct calls on `Github`
 
 ```ruby
 Github.repos.list user: 'wycats'
@@ -56,22 +61,22 @@ or create a new client instance
 github = Github.new
 ```
 
-At this stage you can also supply various configuration parameters, such as
+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
+  auto_pagination  # false by default, set to true to traverse 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
+  user             # global user used in requests 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'
+  org              # global organization used in requests if none provided
+  endpoint         # enterprise API endpoint
+  site             # enterprise API web endpoint
+  ssl              # SSL settings
+  per_page         # number of items per page- max of 100
+  user_agent       # custom user agent name, 'Github API' by default
 ```
 which are used throughout the API. These can be passed directly as hash options:
 
@@ -79,7 +84,7 @@ which are used throughout the API. These can be passed directly as hash options:
 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
+Alternatively, you can configure the GitHub settings by passing a block, for instance, for a custom enterprise endpoint and website like
 
 ```ruby
 github = Github.new do |config|
@@ -91,20 +96,20 @@ github = Github.new do |config|
 end
 ```
 
-You can authenticate either using OAuth authentication convenience methods(see section OAuth) or through basic authentication by passing your login and password credentials
+You can authenticate either using OAuth authentication convenience methods (see OAuth section) or through basic authentication by passing your login and password credentials
 
 ```ruby
 github = Github.new login:'peter-murach', password:'...'
 ```
 
-or use convenience method:
+or using a 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`
+This gem closely mirrors the GitHub API hierarchy i.e. if you want to create a download resource,
+look up 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
 
@@ -121,7 +126,7 @@ 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.
+The response is of type [Github::ResponseWrapper] which allows traversing all the json response attributes like method calls i.e.
 
 ```ruby
 repos = Github::Repos.new :user => 'peter-murach', :repo => 'github'
@@ -132,14 +137,14 @@ end
 
 ## Arguments & Parameters
 
-The library allows for flexible arguments parsing. Therefore arguments can be passed during instance creation:
+The library allows for flexible argument 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:
+Further, arguments can be passed directly inside the 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
@@ -161,7 +166,7 @@ But why limit ourselves? You can mix and match arguments, for example:
   issues.milestones(repo: 'tty').list
 ```
 
-Finally, you can use a bit of syntactic sugar common among ruby libraries whereby "username/repository" can be passed as well:
+You can also use a bit of syntactic sugar common among Ruby libraries whereby "username/repository" can be passed as well:
 
 ```ruby
   issues = Github::Issues.new
@@ -169,7 +174,7 @@ Finally, you can use a bit of syntactic sugar common among ruby libraries whereb
   issues.milestones.list 'peter-murach/github'
 ```
 
-Finally, use `with` scope to clearly denote your requests
+Finally, use the `with` scope to clearly denote your requests
 
 ```ruby
   issues = Github::Issues.new
@@ -199,7 +204,7 @@ end
 
 ## Advanced Configuration
 
-The `github_api` gem will use the default middleware stack which is exposed by calling `stack` on client instance. However, this stack can be freely modified with methods such as `insert`, `insert_after`, `delete` and `swap`. For instance to add your `CustomMiddleware` do
+The `github_api` gem will use the default middleware stack which is exposed by calling `stack` on a client instance. However, this stack can be freely modified with methods such as `insert`, `insert_after`, `delete` and `swap`. For instance, to add your `CustomMiddleware` do
 
 ```ruby
 github = Github.new do |config|
@@ -220,6 +225,7 @@ github = Github.new do |config|
 end
 ```
 
+
 ## API
 
 Main API methods are grouped into the following classes that can be instantiated on their own
@@ -232,25 +238,25 @@ Github::Orgs            Github::Issues     Github::Authorizations
 Github::PullRequests    Github::Users      Github::Activity
 ```
 
-Some parts of GitHub API v3 require you to be autheticated, for instance the following are examples of APIs only for the authenticated user
+Some parts of GitHub API v3 require you to be authenticated, for instance the following are examples of APIs only for the authenticated user
 
 ```ruby
 Github::Users::Emails
 Github::Users::Keys
 ```
 
-All method calls form ruby like sentences and allow for intuitive api navigation, for instance
+All method calls form Ruby like sentences and allow for intuitive API navigation, for instance
 
 ```ruby
 github = Github.new :oauth_token => '...'
 github.users.followers.following 'wycats'  # => returns users that 'wycats' is following
-github.users.followers.following 'wycats' # => returns true if following, otherwise false
+github.users.followers.following? 'wycats' # => returns true if following, otherwise false
 ```
 
-For specification on all available methods go to http://developer.github.com/v3/ or
-read the rdoc, all methods are documented there with examples of usage.
+For specifications on all available methods, go to http://developer.github.com/v3/ or
+read the rdoc. All methods are documented there with examples of usage.
 
-Alternatively, you can find out supported methods by calling `actions` on a class instance in your `irb`:
+Alternatively, you can find out which methods are supported by calling `actions` on a class instance in your `irb`:
 
 ```ruby
 >> Github::Repos.actions                    >> github.issues.actions
@@ -298,14 +304,14 @@ Once you have your access token, configure your github instance following instru
 
 ### Authorizations API
 
-Alternatively you can use OAuth Authorizations API. For instance, to create access token through GitHub API you required to pass your basic credentials as in the following:
+Alternatively, you can use the OAuth Authorizations API. For instance, to create an access token through the GitHub API, you are required to pass your basic credentials as in the following:
 
 ```ruby
 github = Github.new basic_auth: 'login:password'
 github.oauth.create '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).
+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).
 
 ### Scopes
 
@@ -316,7 +322,7 @@ You can check OAuth scopes you have by:
   github.scopes.list    # => ['repo']
 ```
 
-To list the scopes that the particular Github API action checks for do:
+To list the scopes that the particular GitHub API action checks for do:
 
 ```ruby
   repos = Github::Repos.new
@@ -334,7 +340,7 @@ By default requests over SSL are set to OpenSSL::SSL::VERIFY_PEER. However, you
   Github.new ssl: { verify: false }
 ```
 
-If your client fails to find CA certs you can pass other SSL options to specify exactly how the information is sourced
+If your client fails to find CA certs, you can pass other SSL options to specify exactly how the information is sourced
 
 ```ruby
   ssl: {
@@ -360,7 +366,7 @@ github.issues.get 'peter-murach', 'github', 108, media: 'text'
 
 This will be expanded into `application/vnd.github.v3.text+json`
 
-If you wish to specify the version pass `media: 'beta.text'` which will be converted to `application/vnd/github.beta.text+json`.
+If you wish to specify the version, pass `media: 'beta.text'` which will be converted to `application/vnd/github.beta.text+json`.
 
 Finally, you can always pass the whole accept header like so
 
@@ -368,6 +374,11 @@ Finally, you can always pass the whole accept header like so
 github.issues.get 'peter-murach', 'github', 108, accept: 'application/vnd.github.raw'
 ```
 
+## Hypermedia
+
+TODO: explain how it works
+Github::Resource for each *_url key
+
 ## Configuration
 
 Certain methods require authentication. To get your GitHub OAuth v2 credentials,
@@ -386,10 +397,10 @@ 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...
+All parameters can be overwritten each method call by passing a parameters hash.
 
 
-By default no caching will be performed. In order to set the cache do... If no cache type is provided a default memoization is done.
+By default, no caching will be performed. In order to set the cache do... If no cache type is provided, a default memoization is done.
 
 ## Pagination
 
@@ -400,7 +411,7 @@ repos = Github::Repos.new
 repos.list user: 'wycats', per_page: 10, page: 5
 ```
 
-Then you can query pagination information included in the link header by:
+Then you can query the pagination information included in the link header by:
 
 ```ruby
 res.links.first  # Shows the URL of the first page of results.
@@ -428,21 +439,21 @@ while res.has_next_page?
 end
 ```
 
-Alternatively, you can retrieve all pages in one invocation by passing `auto_pagination` option like so:
+Alternatively, you can retrieve all pages in one invocation by passing the `auto_pagination` option like so:
 
 ```ruby
   github = Github.new auto_pagination: true
 ```
 
-Depending at what stage you pass the `auto_pagination` it will affect all or only single request:
+Depending at what stage you pass the `auto_pagination` it will affect all or only a single request:
 
 ```ruby
   Github::Repos.new auto_pagination: true         # affects Repos part of API
 
-  Github::Repos.new.list user: '...', auto_pagination: true  # affects single request
+  Github::Repos.new.list user: '...', auto_pagination: true  # affects a single request
 ```
 
-One can also navigate straight to specific page by:
+One can also navigate straight to the specific page by:
 
 ```ruby
 res.count_pages  # Number of pages
@@ -453,9 +464,17 @@ res.prev_page    # Get previous page
 res.last_page    # Get last page
 ```
 
+### Caching
+
+TODO: explaing how to add faraday-cache midlleware
+
+### Debugging requests
+
+run with ENV['DEBUG'] flag  or include middleware by passing `debug` flag
+
 ## Error Handling
 
-The generic error class `Github::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 erros like
+The generic error class `Github::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
 
 ```ruby
 begin
@@ -473,7 +492,7 @@ end
 
 ## Response Message
 
-Each 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
+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, call
 
 ```ruby
 res = Github::Repos.new.branches 'peter-murach', 'github'
@@ -487,7 +506,7 @@ res.headers.cache_control       # "public, max-age=60, s-maxage=60"
 
 ## Examples
 
-Some api methods require input parameters, these are added simply as a hash properties, for instance
+Some API methods require input parameters. These are simply added as a hash of properties, for instance
 
 ```ruby
 issues = Github::Issues.new user:'peter-murach', repo: 'github-api'
@@ -501,7 +520,7 @@ users = Github::Users.new oauth_token: 'token'
 users.emails.add '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,
+If a method returns a collection, you can iterate over it by supplying a block parameter,
 
 ```ruby
 events = Github::Activity::Events.new
@@ -510,16 +529,16 @@ events.public do |event|
 end
 ```
 
-Query requests instead of http responses return boolean values
+Query requests return boolean values instead of HTTP responses
 
 ```ruby
 github = Github.new
-github.orgs.members.public_member? 'github', 'technoweenie' # => true
+github.orgs.members.member? 'github', 'technoweenie', public: true # => true
 ```
 
 ## Rails Example
 
-A Rails controller that allows a user to authorize their GitHub account and then perform request.
+A Rails controller that allows a user to authorize their GitHub account and then performs a request.
 
 ```ruby
 class GithubController < ApplicationController
@@ -543,11 +562,11 @@ end
 
 ## Testing
 
-The test suite is split into two groups `live` and `mock`.
+The test suite is split into two groups, `live` and `mock`.
 
-The `live` tests are the ones in `features` folder and they simply exercise the GitHub API by making live requests and then being cached with VCR in directory named `features\cassettes`. For details on how to get setup please navigate to `features` folder.
+The `live` tests are the ones in `features` folder and they simply exercise the GitHub API by making live requests and then being cached with VCR in directory named `features\cassettes`. For details on how to get set up, please navigate to the `features` folder.
 
-The `mock` tests are in `spec` directory and their primary concern is to test the gem internals without the hindrance of external calls.
+The `mock` tests are in the `spec` directory and their primary concern is to test the gem internals without the hindrance of external calls.
 
 ## Development
 

data/features/cassettes/repos/assets/delete.yml

@@ -0,0 +1,52 @@
+--- 
+http_interactions: 
+- request: 
+    method: delete
+    uri: https://<BASIC_AUTH>@api.github.com/repos/<USER>/github_api_test/releases/assets/46073?access_token=<TOKEN>
+    body: 
+      encoding: US-ASCII
+      string: ""
+    headers: 
+      Accept: 
+      - application/vnd.github.v3+json,application/vnd.github.beta+json;q=0.5,application/json;q=0.1
+      Accept-Charset: 
+      - utf-8
+      User-Agent: 
+      - Github Ruby Gem 0.10.2
+  response: 
+    status: 
+      code: 204
+      message: No Content
+    headers: 
+      Server: 
+      - GitHub.com
+      Date: 
+      - Sat, 07 Dec 2013 21:27:04 GMT
+      Status: 
+      - 204 No Content
+      X-Ratelimit-Limit: 
+      - "5000"
+      X-Ratelimit-Remaining: 
+      - "4990"
+      X-Ratelimit-Reset: 
+      - "1386451969"
+      X-Github-Media-Type: 
+      - github.v3; format=json
+      X-Content-Type-Options: 
+      - nosniff
+      Access-Control-Allow-Credentials: 
+      - "true"
+      Access-Control-Expose-Headers: 
+      - ETag, Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
+      Access-Control-Allow-Origin: 
+      - "*"
+      X-Github-Request-Id: 
+      - 4D649864:2A9D:172CB9E:52A392A8
+      Vary: 
+      - Accept-Encoding
+    body: 
+      encoding: US-ASCII
+      string: ""
+    http_version: 
+  recorded_at: Sat, 07 Dec 2013 21:27:04 GMT
+recorded_with: VCR 2.6.0

data/features/cassettes/repos/assets/edit.yml

@@ -0,0 +1,65 @@
+--- 
+http_interactions: 
+- request: 
+    method: patch
+    uri: https://<BASIC_AUTH>@api.github.com/repos/murek/github_api_test/releases/assets/46084?access_token=<TOKEN>
+    body: 
+      encoding: UTF-8
+      string: "{\"name\":\"Rake\",\"label\":\"Ruby code\"}"
+    headers: 
+      Accept: 
+      - application/vnd.github.v3+json,application/vnd.github.beta+json;q=0.5,application/json;q=0.1
+      Accept-Charset: 
+      - utf-8
+      User-Agent: 
+      - Github Ruby Gem 0.10.2
+      Content-Type: 
+      - application/json
+  response: 
+    status: 
+      code: 200
+      message: OK
+    headers: 
+      Server: 
+      - GitHub.com
+      Date: 
+      - Sat, 07 Dec 2013 21:16:20 GMT
+      Content-Type: 
+      - application/json; charset=utf-8
+      Status: 
+      - 200 OK
+      X-Ratelimit-Limit: 
+      - "5000"
+      X-Ratelimit-Remaining: 
+      - "4991"
+      X-Ratelimit-Reset: 
+      - "1386451969"
+      Cache-Control: 
+      - private, max-age=60, s-maxage=60
+      Last-Modified: 
+      - Sat, 07 Dec 2013 21:16:20 GMT
+      Etag: 
+      - "\"00bde8b488647e7a3b3ba20a812788e6\""
+      Vary: 
+      - Accept, Authorization, Cookie, X-GitHub-OTP
+      - Accept-Encoding
+      X-Github-Media-Type: 
+      - github.v3; format=json
+      X-Content-Type-Options: 
+      - nosniff
+      Content-Length: 
+      - "290"
+      Access-Control-Allow-Credentials: 
+      - "true"
+      Access-Control-Expose-Headers: 
+      - ETag, Link, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-OAuth-Scopes, X-Accepted-OAuth-Scopes, X-Poll-Interval
+      Access-Control-Allow-Origin: 
+      - "*"
+      X-Github-Request-Id: 
+      - 4D649864:70CB:1D9EC01:52A39023
+    body: 
+      encoding: US-ASCII
+      string: "{\"url\":\"https://api.github.com/repos/murek/github_api_test/releases/assets/46084\",\"id\":46084,\"name\":\"Rake\",\"label\":\"Ruby code\",\"content_type\":\"application/octet-stream\",\"state\":\"uploaded\",\"size\":333,\"download_count\":0,\"created_at\":\"2013-12-07T21:00:29Z\",\"updated_at\":\"2013-12-07T21:16:20Z\"}"
+    http_version: 
+  recorded_at: Sat, 07 Dec 2013 21:16:20 GMT
+recorded_with: VCR 2.6.0