github_api 0.2.0 → 0.2.1

data/README.rdoc

@@ -12,7 +12,7 @@ Grab the gem by issuing
 
 or in your Gemfile
 
-  gem "github_api", "~> 0.2.0"
+  gem "github_api", "~> 0.2.1"
 
 == Usage
 
@@ -20,20 +20,12 @@ Create a new client instance
 
   @github = Github.new
 
-At this stage you can also supply various configuration parameters, such as :user, :repo, :org, :oauth_token, :login, :password or :basic_auth
-which are used thoughtout the API
+At this stage you can also supply various configuration parameters, such as :user, :repo, :org, :oauth_token, :login, :password or :basic_auth which are used thoughtout the API
 
   @github = Github.new :user => 'peter-murach', :repo => 'github-api'
 
-In order to authenticate the user through OAuth2 on GitHub you need to
-
-* visit https://github.com/account/applications/ and register your app
-* authorize your credentials https://github.com/login/oauth/authorize
-* get your token https://github.com/login/oauth/access_token
+You can authenticate either using OAuth authentication convenience methods(see section OAuth) or through basic authentication by passing your login and password credentials
 
-Once you have your consumer and token keys, configure your github instance following instructions under Configuration.
-
-You can also use basic authentication by passing your login and password credentials
   @github = Github.new :login => 'peter-murach', :password => '...'
 
   or use convenience method:
@@ -85,7 +77,7 @@ All method calls form ruby like sentences and allow for intuitive api navigation
 
   @github = Github.new :oauth_token => '...'
   @github.users.following 'wycats'  # => returns users that 'wycats' is following
-  @github.users.following? 'wycats' # => returns true if following, otherwise false
+  @github.users.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.
@@ -106,14 +98,35 @@ or organisation name, allow you to switch the way the data is returned to you, f
     puts file.path
   end
 
+== OAuth
+
+In order to authenticate the user through OAuth2 on GitHub you need to
+
+* visit https://github.com/account/applications/ and register your app
+
+* authorize your credentials https://github.com/login/oauth/authorize
+  You can use convenience methods to help you achieve this that come with this gem:
+
+    @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
+
+    token = github.get_token( authorization_code )
+
+Once you have your access token, configure your github instance following instructions under Configuration.
+
 == MIME Types
 
-Provides support for the following mime types
+Issues, 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.
 
 In order to pass a mime type with your request do
 
-  @github = Github.new :oauth_token
-  @github...
+  @github = Github.new
+  @github.pull_requests.pull_requests 'peter-murach', 'github', :mime_type => :full
+
+  Your header will contain 'Accept: "application/vnd.github-pull.full+json"' which in turn returns raw, text and html representations in response body.
 
 == Configuration
 
@@ -132,6 +145,12 @@ or
 
 All parameters can be overwirtten as per method call. By passing parameters hash...
 
+== Caching
+
+Each <tt>get</tt> 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.
+
+  Github.cache do...
+
 == Examples
 
 Some api methods require input parameters, these are added simply as a hash properties, for instance
@@ -156,17 +175,29 @@ Query requests instead of http responses return boolean values
   @github = Github.new
   @github.orgs.public_member? 'github', 'technoweenie' # => true
 
-== Caching
+== Rails Example
+
+A Rails controller that allows a user to authorize their GitHub account and then perform request.
 
-Each call by default is not going to be cached. In order to set the inmemory cache do...
+  class GithubController < ApplicationController
+
+    def authorize
+      github = Github.new :client_id => '...', :client_secret => '...'
+      address = github.authorize_url :redirect_uri => 'http://...', :scope => 'repo'
+      redirect_to address
+    end
+
+    def callback
+      authorization_code = params[:code]
+      token = github.get_token authorization_code
+      access_token = token.token
+    end
+  end
 
 == TODO
 
-* Add support for mime types
 * Add request caching - local filestore?, http caching?.
-* Add oauth2 helper methods.
 * Add response processing methods
-* Add helper methods to return iterators over most common collections.
 * Add response set helper methods e.i. pagination.
 * Add DSL falvoured api access
 

data/lib/github_api.rb

@@ -51,6 +51,8 @@ module Github
     :Orgs         => 'orgs',
     :PullRequests => 'pull_requests',
     :Users        => 'users',
-    :CoreExt      => 'core_ext'
+    :CoreExt      => 'core_ext',
+    :MimeType     => 'mime_type',
+    :Authorization => 'authorization'
 
 end # Github

data/lib/github_api/api.rb

@@ -3,12 +3,16 @@
 require 'github_api/configuration'
 require 'github_api/connection'
 require 'github_api/request'
+require 'github_api/mime_type'
 require 'github_api/core_ext/hash'
 require 'github_api/core_ext/array'
 
 module Github
+
   # @private
   class API
+    include Authorization
+    include MimeType
     include Connection
     include Request
 
@@ -37,7 +41,7 @@ module Github
         send("#{key}=", options[key])
       end
       _process_basic_auth(options[:basic_auth])
-      @cached = Hash.new
+      client if client_id? && client_secret?
     end
 
   private
@@ -143,7 +147,9 @@ module Github
       end
     end
 
-    def _merge_parameters(params)
+    def _merge_mime_type(resource, params) # :nodoc:
+      params['resource'] = resource
+      params['mime_type'] = params['mime_type'] || :raw
     end
 
     # TODO add to core extensions

data/lib/github_api/authorization.rb

@@ -0,0 +1,52 @@
+# encoding: utf-8
+
+module Github
+  module Authorization
+
+    attr_accessor :scopes
+
+    # Setup OAuth2 instance
+    def client
+      @client ||= ::OAuth2::Client.new(client_id, client_secret,
+        :site          => 'https://github.com',
+        :authorize_url => 'login/oauth/authorize',
+        :token_url     => 'login/oauth/access_token'
+      )
+    end
+
+    # Strategy token
+    def auth_code
+      _verify_client
+      @client.auth_code
+    end
+
+    # Sends authorization request to GitHub.
+    # = Parameters
+    # * <tt>:redirect_uri</tt> - Required string.
+    # * <tt>:scope</tt> - Optional string. Comma separated list of scopes.
+    #   Available scopes:
+    #   * (no scope) - public read-only access (includes public user profile info, public repo info, and gists).
+    #   * <tt>user</tt> - DB read/write access to profile info only.
+    #   * <tt>public_repo</tt> - DB read/write access, and Git read access to public repos.
+    #   * <tt>repo</tt> - DB read/write access, and Git read access to public and private repos.
+    #   * <tt>gist</tt> - write access to gists.
+    #
+    def authorize_url(params = {})
+      _verify_client
+      @client.auth_code.authorize_url(params)
+    end
+
+    # Makes request to token endpoint and retrieves access token value
+    def get_token(authorization_code, params = {})
+      _verify_client
+      @client.auth_code.get_token(authorization_code, params)
+    end
+
+    private
+
+    def _verify_client # :nodoc:
+      raise ArgumentError, 'Need to provide client_id and client_secret' unless client_id? && client_secret?
+    end
+
+  end # Authorization
+end # Github

data/lib/github_api/cache_control.rb

@@ -0,0 +1,19 @@
+module Github
+  module CacheOptions
+    extend self
+
+    def self.option_accessor(key)
+      defined_method("#{key}=") { |value|  }
+    end
+
+  private 
+
+    def initialize_options(options={})
+      @default_options = {
+        'type' => :memoization,
+
+      }
+    end
+
+  end
+end

data/lib/github_api/configuration.rb

@@ -9,10 +9,9 @@ module Github
       :client_secret,
       :oauth_token,
       :endpoint,
-      :format,
-      :resource,
+      :mime_type,
       :user_agent,
-      :faraday_options,
+      :connection_options,
       :repo,
       :user,
       :login,
@@ -47,12 +46,11 @@ module Github
     # The value sent in the http header for 'User-Agent' if none is set
     DEFAULT_USER_AGENT = "Github Ruby Gem #{Github::VERSION::STRING}".freeze
 
-    DEFAULT_FORMAT = :json
+    # By default the <tt>Accept</tt> header will make a request for <tt>JSON</tt>
+    DEFAULT_MIME_TYPE = :json
 
-    # By default,  
-    DEFAULT_RESOURCE = nil
-
-    DEFAULT_FARADAY_OPTIONS = {}
+    # By default uses the Faraday connection options if none is set
+    DEFAULT_CONNECTION_OPTIONS = {}
 
     # By default, don't set user name
     DEFAULT_USER = nil
@@ -84,9 +82,8 @@ module Github
       self.oauth_token        = DEFAULT_OAUTH_TOKEN
       self.endpoint           = DEFAULT_ENDPOINT
       self.user_agent         = DEFAULT_USER_AGENT
-      self.faraday_options    = DEFAULT_FARADAY_OPTIONS
-      self.format             = DEFAULT_FORMAT
-      self.resource           = DEFAULT_RESOURCE
+      self.connection_options = DEFAULT_CONNECTION_OPTIONS
+      self.mime_type          = DEFAULT_MIME_TYPE
       self.user               = DEFAULT_USER
       self.repo               = DEFAULT_REPO
       self.login              = DEFAULT_LOGIN

data/lib/github_api/connection.rb

@@ -11,55 +11,38 @@ require 'github_api/request/basic_auth'
 module Github
   module Connection
 
-    # Available resources 
-    RESOURCES = {
-      :issue         => 'vnd.github-issue.',
-      :issuecomment  => 'vnd.github-issuecomment.',
-      :commitcomment => 'vnd.github-commitcomment',
-      :pull          => 'vnd.github-pull.',
-      :pullcomment   => 'vnd.github-pullcomment.',
-      :gistcomment   => 'vnd.github-gistcomment.'
-    }
-
-    # Mime types used by resources
-    RESOURCE_MIME_TYPES = {
-      :raw  => 'raw+json',
-      :text => 'text+json',
-      :html => 'html+json',
-      :full => 'html+full'
-    }
-
-    BLOB_MIME_TYPES = {
-      :raw => 'vnd.github-blob.raw',
-      :json => 'json'
-    }
-
-    def default_faraday_options()
+  private
+
+    def header_options() # :nodoc:
       {
         :headers => {
-          'Accept' => "application/#{resource}#{format}",
-          'User-Agent' => user_agent
+          'Accept'       => '*/*', #accepts,
+          'User-Agent'   => user_agent,
+          'Content-Type' => 'application/x-www-form-urlencoded'
         },
         :ssl => { :verify => false },
         :url => endpoint
       }
     end
 
-    # TODO Write mime format conversion
-
-    # Create cache hash and store connection there and then pass it to @connection
-    # add method to invalidate it if previous options are different from current
-
-    def clear_cache
+    def clear_cache # :nodoc:
       @connection = nil
     end
 
-    def caching?
+    def caching? # :nodoc:
       !@connection.nil?
     end
 
-    def connection(options = {})
-      merged_options = faraday_options.merge(default_faraday_options)
+    def connection(options = {}) # :nodoc:
+
+      # parse(options['resource'], options['mime_type'] || mime_type) if options['mime_type']
+      debugger
+
+      merged_options = if connection_options.empty?
+        header_options
+      else
+        connection_options.merge(header_options)
+      end
 
       clear_cache unless options.empty?
 
@@ -89,4 +72,3 @@ module Github
 
   end # Connection
 end # Github
-

data/lib/github_api/gists/comments.rb

@@ -4,8 +4,12 @@ module Github
   class Gists
     module Comments
 
-      REQUIRED_GIST_COMMENT_INPUTS = %w[ body ]
-      
+      REQUIRED_GIST_COMMENT_INPUTS = %w[ 
+        body
+        mime_type
+        resource
+      ].freeze
+
       # List comments on a gist
       #
       # = Examples
@@ -14,6 +18,8 @@ module Github
       #
       def gist_comments(gist_id, params={})
         _normalize_params_keys(params)
+        _merge_mime_type(:gist_comment, params)
+
         get("/gists/#{gist_id}/comments", params)
       end
 
@@ -25,6 +31,8 @@ module Github
       #
       def gist_comment(comment_id, params={})
         _normalize_params_keys(params)
+        _merge_mime_type(:gist_comment, params)
+
         get("/gists/comments/#{comment_id}", params)
       end
 
@@ -36,8 +44,9 @@ module Github
       #
       def create_gist_comment(gist_id, params={})
         _normalize_params_keys(params)
+        _merge_mime_type(:gist_comment, params)
         _filter_params_keys(REQUIRED_GIST_COMMENT_INPUTS, params)
-        
+
         raise ArgumentError, "Required inputs are: :body" unless _validate_inputs(REQUIRED_GIST_COMMENT_INPUTS, params)
 
         post("/gists/#{gist_id}/comments", params)
@@ -51,8 +60,9 @@ module Github
       #
       def edit_gist_comment(comment_id, params={})
         _normalize_params_keys(params)
+        _merge_mime_type(:gist_comment, params)
         _filter_params_keys(REQUIRED_GIST_COMMENT_INPUTS, params)
-        
+
         raise ArgumentError, "Required inputs are: :body" unless _validate_inputs(REQUIRED_GIST_COMMENT_INPUTS, params)
 
         patch("/gists/comments/#{comment_id}", params)
@@ -66,9 +76,11 @@ module Github
       #
       def delete_gist_comment(comment_id, params={})
         _normalize_params_keys(params)
+        _merge_mime_type(:gist_comment, params)
+
         delete("/gists/comments/#{comment_id}", params)
       end
-       
+
     end # Comments
   end # Gists
 end # Github

data/lib/github_api/issues.rb

@@ -27,6 +27,8 @@ module Github
       mentioned
       title
       body
+      resource
+      mime_type
     ]
 
     VALID_ISSUE_PARAM_VALUES = {
@@ -58,7 +60,7 @@ module Github
     #
     # = Examples
     #  @github = Github.new :oauth_token => '...'
-    #  @github.issues.issues :since => '2011-04-12312:12:121', 
+    #  @github.issues.issues :since => '2011-04-12312:12:121',
     #    :filter => 'created',
     #    :state  => 'open',
     #    :labels => "bug,ui,bla",
@@ -68,6 +70,7 @@ module Github
     def issues(params={})
       _normalize_params_keys(params)
       _filter_params_keys(VALID_ISSUE_PARAM_NAMES, params)
+      _merge_mime_type(:issue, params)
       _validate_params_values(VALID_ISSUE_PARAM_VALUES, params)
 
       response = get("/issues", params)
@@ -111,6 +114,7 @@ module Github
 
       _normalize_params_keys(params)
       _filter_params_keys(VALID_ISSUE_PARAM_NAMES, params)
+      _merge_mime_type(:issue, params)
       _validate_params_values(VALID_ISSUE_PARAM_VALUES, params)
 
       response = get("/repos/#{user}/#{repo}/issues", params)
@@ -127,7 +131,9 @@ module Github
     def get_issue(user_name, repo_name, issue_id, params={})
       _update_user_repo_params(user_name, repo_name)
       _validate_user_repo_params(user, repo) unless user? && repo?
+
       _normalize_params_keys(params)
+      _merge_mime_type(:issue, params)
 
       get("/repos/#{user}/#{repo}/issues/#{issue_id}")
     end
@@ -157,6 +163,7 @@ module Github
       _validate_user_repo_params(user, repo) unless user? && repo?
 
       _normalize_params_keys(params)
+      _merge_mime_type(:issue, params)
       _filter_params_keys(VALID_MILESTONE_INPUTS, params)
 
       raise ArgumentError, "Required params are: :title" unless _validate_inputs(%w[ title ], params)
@@ -192,6 +199,7 @@ module Github
       _validate_presence_of issue_id
 
       _normalize_params_keys(params)
+      _merge_mime_type(:issue, params)
       _filter_params_keys(VALID_MILESTONE_INPUTS, params)
 
       patch("/repos/#{user}/#{repo}/issues/#{issue_id}", params)