github_api 0.11.2 → 0.11.3

data/README.md

@@ -16,7 +16,7 @@
 
 A Ruby wrapper for the GitHub REST API v3.
 
-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.
+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::Repos.new if working solely with repositories is your main concern.
 
 ## Features
 
@@ -31,7 +31,7 @@ Supports all the API methods (nearly 200). It's built in a modular way. You can
 * Supports multithreaded environment.
 * 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 1000 features. [testing](#testing)
+* Fully tested with test coverage above 90% with over 1,700 specs and 1000 features. [testing](#testing)
 
 ## Installation
 
@@ -47,7 +47,26 @@ or put it in your Gemfile and run `bundle install`
 gem "github_api"
 ```
 
-## Usage
+## Contents
+
+* [1. Usage](#1-usage)
+* [2. Arguments & Parameters](#2-arguments--parameters)
+* [3. Advanced Configuration](#3-advanced-configuration)
+* [4. Authentication](#4-authentication)
+* [5. SSL](#5-ssl)
+* [6. API](#6-api)
+* [7. Media Types](#7-media-types)
+* [8. Hypermeida](#8-hypermedia)
+* [9. Configuration](#9-configurations)
+* [10. Pagination](#10-pagination)
+* [11. Caching](#11-caching)
+* [12. Debugging](#12-debugging)
+* [13. Error Handling](#13-error-handling)
+* [14. Response Message](#14-response-message)
+* [15. Examples](#15-examples)
+* [16. Testing](#16-testing)
+
+## 1 Usage
 
 To start using the gem, you can either perform direct calls on `Github`
 
@@ -61,6 +80,8 @@ or create a new client instance
 github = Github.new
 ```
 
+### 1.1 Options
+
 At this stage, you can also supply various configuration parameters, such as
 ```
   adapter          # http client used for performing requests
@@ -108,6 +129,8 @@ or using a convenience method:
 github = Github.new basic_auth: 'login:password'
 ```
 
+### 1.2 API navigation
+
 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`
 
@@ -119,6 +142,8 @@ github.repos.hooks.create 'user-name', 'repo-name', name: "web", active: true
 github.repos.keys.get     'user-name', 'repo-name'
 ```
 
+### 1.3 Modularity
+
 The code base is modular and allows for you to work specifically with a given part of GitHub API e.g. blobs
 
 ```ruby
@@ -126,18 +151,19 @@ blobs = Github::GitData::Blobs.new
 blobs.create 'peter-murach', 'github', content: 'Blob content'
 ```
 
+### 1.4 Response querying
 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'
+repos = Github::Repos.new user: 'peter-murach', repo: 'github'
 repos.branches do |branch|
   puts branch.name
 end
 ```
 
-## Arguments & Parameters
+## 2 Arguments & Parameters
 
-The library allows for flexible argument parsing. Therefore, arguments can be passed during instance creation:
+The **GithubAPI** library allows for flexible argument parsing. Therefore, arguments can be passed during instance creation:
 
 ```ruby
   issues = Github::Issues.new user: 'peter-murach', repo: 'github'
@@ -178,7 +204,7 @@ Finally, use the `with` scope to clearly denote your requests
 
 ```ruby
   issues = Github::Issues.new
-  issues.milestones.with(user:'peter-murach', repo: 'github').list
+  issues.milestones.with(user: 'peter-murach', repo: 'github').list
 ```
 
 Some API methods apart from required parameters such as username, repository name
@@ -202,7 +228,7 @@ github.git_data.trees.get 'peter-murach', 'github', 'c18647b75d72f19c1e0cc8af031
 end
 ```
 
-## Advanced Configuration
+## 3 Advanced Configuration
 
 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
 
@@ -225,71 +251,32 @@ github = Github.new do |config|
 end
 ```
 
+## 4 Authentication
 
-## API
+### 4.1 Basic
 
-Main API methods are grouped into the following classes that can be instantiated on their own
+To start making requests as authenticated user you can use your GitHub username and password like so
 
 ```ruby
-Github         - full API access
-
-Github::Gists           Github::GitData    Github::Repos             Github::Search
-Github::Orgs            Github::Issues     Github::Authorizations
-Github::PullRequests    Github::Users      Github::Activity
+Github.new basic_auth: 'login:password'
 ```
 
-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
-
-```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
-```
-
-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 which methods are supported by calling `actions` on a class instance in your `irb`:
+Though this method is convenient you should strongly consider using `OAuth` for improved security reasons.
 
-```ruby
->> Github::Repos.actions                    >> github.issues.actions
----                                         ---
-|--> all                                    |--> all
-|--> branches                               |--> comments
-|--> collaborators                          |--> create
-|--> commits                                |--> edit
-|--> contribs                               |--> events
-|--> contributors                           |--> find
-|--> create                                 |--> get
-|--> downloads                              |--> labels
-|--> edit                                   |--> list
-|--> find                                   |--> list_repo
-|--> forks                                  |--> list_repository
-|--> get                                    |--> milestones
-|--> hooks                                  ...
-...
-```
+### 4.2 Application OAuth access
 
-## OAuth
+In order to authenticate your app through OAuth2 on GitHub you need to
 
-In order to authenticate the user through OAuth2 on GitHub you need to
-
-* visit https://github.com/settings/applications/new and register your app
+* Visit https://github.com/settings/applications/new and register your app.
   You will need to be logged in to initially register the application.
 
-* authorize your credentials https://github.com/login/oauth/authorize
-  You can use convenience methods to help you achieve this that come with this gem:
+* Authorize your credentials https://github.com/login/oauth/authorize
+
+You can use convenience methods to help you achieve this using **GithubAPI** gem:
 
 ```ruby
-github = Github.new :client_id => '...', :client_secret => '...'
-github.authorize_url :redirect_uri => 'http://localhost', :scope => 'repo'
+github = Github.new client_id: '...', client_secret: '...'
+github.authorize_url redirect_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
@@ -302,18 +289,42 @@ Once you have your access token, configure your github instance following instru
 
 **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 a ```redirect_uri_mismatch``` error.
 
-### Authorizations API
+### 4.3 Authorizations API
+
+#### 4.3.1 For an User
 
-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:
+To create an access token through the GitHub Authrizations API, you are required to pass your basic credentials and scopes you wish to have for the authentication token.
 
 ```ruby
 github = Github.new basic_auth: 'login:password'
-github.oauth.create 'scopes' => ['repo']
+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).
 
-### Scopes
+#### 4.3.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.
+
+```ruby
+github = Github.new basic_auth: 'login:password'
+github.oauth.app.create 'clinet-id', scopes: ['repo']
+```
+
+In order to revoke auth token(s) for an application you must use basic authentication with `client_id` as login and `client_secret` as password.
+
+```ruby
+github = Github.new basic_auth: "client_id:client_secret"
+github.oauth.app.delete 'client-id'
+```
+
+Revoke a specific app token.
+
+```ruby
+github.oauth.app.delete 'client-id', 'access-token'
+```
+
+### 4.4 Scopes
 
 You can check OAuth scopes you have by:
 
@@ -332,7 +343,7 @@ To list the scopes that the particular GitHub API action checks for do:
 
 To understand what each scope means refer to [documentation](http://developer.github.com/v3/oauth/#scopes)
 
-## SSL
+## 5 SSL
 
 By default requests over SSL are set to OpenSSL::SSL::VERIFY_PEER. However, you can turn off peer verification by
 
@@ -354,7 +365,58 @@ If your client fails to find CA certs, you can pass other SSL options to specify
 For instance, download CA root certificates from Mozilla [cacert](http://curl.haxx.se/ca/cacert.pem) and point ca_file at your certificate bundle location.
 This will allow the client to verify the github.com ssl certificate as authentic.
 
-## Media Types
+## 6 API
+
+Main API methods are grouped into the following classes that can be instantiated on their own
+
+```ruby
+Github         - full API access
+
+Github::Gists           Github::GitData    Github::Repos             Github::Search
+Github::Orgs            Github::Issues     Github::Authorizations
+Github::PullRequests    Github::Users      Github::Activity
+```
+
+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
+
+```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
+```
+
+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 which methods are supported by calling `actions` on a class instance in your `irb`:
+
+```ruby
+>> Github::Repos.actions                    >> github.issues.actions
+---                                         ---
+|--> all                                    |--> all
+|--> branches                               |--> comments
+|--> collaborators                          |--> create
+|--> commits                                |--> edit
+|--> contribs                               |--> events
+|--> contributors                           |--> find
+|--> create                                 |--> get
+|--> downloads                              |--> labels
+|--> edit                                   |--> list
+|--> find                                   |--> list_repo
+|--> forks                                  |--> list_repository
+|--> get                                    |--> milestones
+|--> hooks                                  ...
+...
+```
+
+## 7 Media Types
 
 You can specify custom media types to choose the format of the data you wish to receive. To make things easier you can specify the following shortcuts
 `json`, `blob`, `raw`, `text`, `html`, `full`. For instance:
@@ -374,12 +436,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
+## 8 Hypermedia
 
-TODO: explain how it works
-Github::Resource for each *_url key
+TODO
 
-## Configuration
+## 9 Configuration
 
 Certain methods require authentication. To get your GitHub OAuth v2 credentials,
 register an app at https://github.com/settings/applications/
@@ -402,7 +463,7 @@ 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.
 
-## Pagination
+## 10 Pagination
 
 Any request that returns multiple items will be paginated to 30 items by default. You can specify custom `page` and `per_page` query parameters to alter default behavior. For instance:
 
@@ -464,15 +525,15 @@ res.prev_page    # Get previous page
 res.last_page    # Get last page
 ```
 
-### Caching
+## 11 Caching
 
 TODO: explaing how to add faraday-cache midlleware
 
-### Debugging requests
+## 12 Debugging
 
 run with ENV['DEBUG'] flag  or include middleware by passing `debug` flag
 
-## Error Handling
+## 13 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 errors like
 
@@ -490,7 +551,7 @@ rescue Github::Error::GithubError => e
 end
 ```
 
-## Response Message
+## 14 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 codes, call
 
@@ -504,7 +565,7 @@ res.headers.etag                # "\"2c5dfc54b3fe498779ef3a9ada9a0af9\""
 res.headers.cache_control       # "public, max-age=60, s-maxage=60"
 ```
 
-## Examples
+## 15 Examples
 
 Some API methods require input parameters. These are simply added as a hash of properties, for instance
 
@@ -536,7 +597,7 @@ github = Github.new
 github.orgs.members.member? 'github', 'technoweenie', public: true # => true
 ```
 
-## Rails Example
+### 15.1 Rails Example
 
 A Rails controller that allows a user to authorize their GitHub account and then performs a request.
 
@@ -560,7 +621,7 @@ class GithubController < ApplicationController
 end
 ```
 
-## Testing
+## 16 Testing
 
 The test suite is split into two groups, `live` and `mock`.
 

data/Rakefile

@@ -12,4 +12,16 @@ Cucumber::Rake::Task.new(:features)
 
 FileList['tasks/**/*.rake'].each { |task| import task }
 
-task :default => [:spec, :features]
+task default: [:spec, :features]
+
+desc 'Run all specs'
+task ci: %w[ spec features ]
+
+desc 'Load gem inside irb console'
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require File.join(__FILE__, '../lib/github_api')
+  ARGV.clear
+  IRB.start
+end

data/features/cassettes/{auths/list.yml → repos/pages/get.yml}

@@ -2,7 +2,7 @@
 http_interactions: 
 - request: 
     method: get
-    uri: https://<BASIC_AUTH>@api.github.com/authorizations?access_token=<TOKEN>
+    uri: https://<BASIC_AUTH>@api.github.com/repos/<USER>/github_api_test/pages?access_token=<TOKEN>
     body: 
       encoding: US-ASCII
       string: ""
@@ -12,7 +12,7 @@ http_interactions:
       Accept-Charset: 
       - utf-8
       User-Agent: 
-      - Github Ruby Gem 0.11.0
+      - Github Ruby Gem 0.11.2
       Accept-Encoding: 
       - gzip;q=1.0,deflate;q=0.6,identity;q=0.3
   response: 
@@ -23,7 +23,7 @@ http_interactions:
       Server: 
       - GitHub.com
       Date: 
-      - Sun, 08 Dec 2013 22:23:35 GMT
+      - Sun, 16 Feb 2014 19:19:10 GMT
       Content-Type: 
       - application/json; charset=utf-8
       Transfer-Encoding: 
@@ -33,13 +33,15 @@ http_interactions:
       X-Ratelimit-Limit: 
       - "5000"
       X-Ratelimit-Remaining: 
-      - "4999"
+      - "4985"
       X-Ratelimit-Reset: 
-      - "1386545015"
+      - "1392579836"
       Cache-Control: 
       - private, max-age=60, s-maxage=60
+      Last-Modified: 
+      - Sun, 16 Feb 2014 19:08:04 GMT
       Etag: 
-      - "\"557c29896b5b01f5dac1fa48fb0c0736\""
+      - "\"db416c75241ecab92cbb45b1addc0279\""
       Vary: 
       - Accept, Authorization, Cookie, X-GitHub-OTP
       - Accept-Encoding
@@ -54,16 +56,16 @@ http_interactions:
       Access-Control-Allow-Origin: 
       - "*"
       X-Github-Request-Id: 
-      - 4D649864:70CD:3738031:52A4F167
+      - 4D649864:3BA3:2B05E2C:53010F2D
       Content-Encoding: 
       - gzip
     body: 
       encoding: ASCII-8BIT
-      string: !binary |-
-        H4sIAAAAAAAAA2WPOw4CMQxE7+J6NcTjBCdcZbU1IIotoEPcHQcWCUIxhZ/m
-        I9/ltK6XqxxmYXI0BxkqtjPKJCWhOJQV2vyNNMXhGsqh+u2jKfa6kQxagVZD
-        bn+In/7NpTU2hyT79m8y0NjfEbtrmeR4vo2P2Gt7eTwBsL4sp+gAAAA=
+      string: !binary |
+        H4sIAAAAAAAAAz3KMQqAMAxA0btkLsahUy9TYolVbG1pkkm8u4Lg+B//AhsF
+        AmyqXQIi9X3Ku262TKlVHNybYLXBB34c3yMqi2KnzAIORElNIJxWioN0UuU/
+        TLTV6GcPYaUifD+TnpLscAAAAA==
 
     http_version: 
-  recorded_at: Sun, 08 Dec 2013 22:23:35 GMT
+  recorded_at: Sun, 16 Feb 2014 19:19:10 GMT
 recorded_with: VCR 2.6.0