google-api 0.0.1.alpha → 0.0.1.beta

data/CHANGELOG.md

@@ -1,3 +1,13 @@
-## v0.0.1.alpha (2012-08-21) ##
+## v0.0.1.beta (2012-09-05)
+
+* Full test suite for all classes and modules.
+* Rethink and rebuild the API integration. Now discover the API and build methods dynamically! Works with the following Google APIs:
+  * Calendar
+  * Drive
+* Add logger configuration.
+* Add the #google method to an oauthable object.
+* Add the #patch method to OAuth2.
+
+## v0.0.1.alpha (2012-08-21)
 
 * First release. (be careful!)

data/README.md

@@ -1,12 +1,10 @@
-**This gem is not yet released! Proceed at your own risk...**
+**This gem is in its infancy! Proceed at your own risk...**
 
-Google API
-===================
+# Google API
 
 A simple but powerful ruby API wrapper for Google's services.
 
-Installation
--------
+## Installation
 
 Add this line to your application's Gemfile:
 
@@ -21,17 +19,15 @@ Or install it yourself as:
     $ gem install google-api
 
 
-Before Using this Gem
--------
+## Before Using this Gem
 
 Google API depends on you to authenticate each user with Google via OAuth2. We don't really care how you get authenticated, but you must request access to a User's Google account and save the Refresh Token, Access Token, and Access Token Expiration Date.
 
 As a starting point, we recommend using Omniauth for most authentication with Ruby. It is a great gem, and integrates seemlessly with most SSO sites, including Google. Check out the [Wiki](https://github.com/agrobbin/google-api/wiki/Using-Omniauth-for-Authentication) for more information.
 
-Usage
--------
+## Usage
 
-This gem couldn't be easier to set up. Once you have a Client ID and Secret from Google (check out the [Wiki](https://github.com/agrobbin/google-api/wiki/Getting-a-Client-ID-and-Secret-from-Google) for instructions on how to get these), you just need to add an initializer to your Rails application that looks like this:
+This gem couldn't be easier to set up. Once you have a Client ID and Secret from Google (check out the [Wiki](https://github.com/agrobbin/google-api/wiki/Getting-a-Client-ID-and-Secret-from-Google) for instructions on how to get these), you just need to add an initializer to your application that looks like this:
 
 ```ruby
 GoogleAPI.configure do |config|
@@ -64,12 +60,20 @@ Once you have set that up, making a request to the Google API is as simple as:
 
 ```ruby
 user = User.find(1)
-client = GoogleAPI::Client.new(user)
-client.drive.all
+user.google.drive.files.list
 ```
 
 This will fetch all files and folders in the user's Google Drive and return them in an array of hashes.
 
+## What Google APIs can this gem be used for?
+
+* Calendar
+* Drive
+
+## I need to use an API that is not yet included
+
+Open an issue, and we will do our best to integrate and fully test the API you need. Or, you can submit a pull request with the necessary updates!
+
 ## Contributing
 
 1. Fork it

data/google-api.gemspec

@@ -4,17 +4,17 @@ Gem::Specification.new do |gem|
   gem.email         = ["alex@robbinsweb.biz"]
   gem.summary       = %q{A simple but powerful ruby API wrapper for Google's services.}
   gem.description   = gem.summary
-  gem.homepage      = ""
+  gem.homepage      = "https://github.com/agrobbin/google-api"
 
   gem.files         = `git ls-files`.split($\)
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.name          = "google-api"
   gem.require_paths = ["lib"]
-  gem.version       = "0.0.1.alpha"
+  gem.version       = "0.0.1.beta"
 
-  gem.add_runtime_dependency 'oauth2', '0.8.0'
-  gem.add_runtime_dependency 'rails', '>= 3.2'
+  gem.add_runtime_dependency 'mime-types', '~> 1.0'
+  gem.add_runtime_dependency 'oauth2', '~> 0.8.0'
   gem.add_development_dependency 'bundler'
   gem.add_development_dependency 'rake'
   gem.add_development_dependency 'rspec'

data/lib/google-api/active_record_inclusions.rb

@@ -25,6 +25,10 @@ module GoogleAPI
           self.oauth_access_token_expires_at = 59.minutes.from_now
           self.save
         end
+
+        define_method :google do
+          GoogleAPI::Client.new(self)
+        end
       end
 
     end

data/lib/google-api/api.rb

@@ -1,109 +1,135 @@
 module GoogleAPI
   class API
 
-    FORMAT = :json
+    attr_reader :access_token, :api, :map
 
-    attr_reader :access_token
-
-    def initialize(access_token)
+    def initialize(access_token, api, map)
       @access_token = access_token
+      @api = api
+      @map = map
     end
 
-    # The really important part of this parent class. The headers are injected here,
-    # and the full URL is built from the ENDPOINT constant and the value passed thru
-    # the URL parameter.
+    # Taking over #method_missing here allows us to chain multiple methods onto a API
+    # instance. If the current place we are in the API includes this method, then let's call it!
+    # If not, and there are multiple methods below this section of the API, build a new API
+    # and do it all over again.
+    #
+    # As an example:
+    #
+    #   User.find(1).google.drive.files.list => we will be calling this method twice, once to find all
+    #   methods within the files section of the API, and once to send a request to the #list API method,
+    #   delegating to the #request method above.
     #
-    # The response is then returned, and appropriately parsed.
-    def request(method, url = nil, args = {})
-      args[:headers] = headers.merge(args[:headers] || {})
-      args[:body] = args[:body].send("to_#{format}") if args[:body].is_a?(Hash)
+    #   User.find(1).google.drive.files.permissions.list => we will end up calling this method three times,
+    #   until we get to the end of the chain.
+    #   (Note: This method chain doesn't map to an actual Google Drive API method.)
+    #
+    # If the API method includes a mediaUpload key, we know that this method allows uploads, like to upload
+    # a new Google Drive file. If so, we call the #upload method instead of #request.
+    def method_missing(method, *args)
+      api_method = map[method.to_s]
+      args = args.last.is_a?(Hash) ? args.last : {} # basically #extract_options!
+      methods_or_resources = api_method['methods'] || api_method['resources']
+      if methods_or_resources
+        API.new(access_token, api, methods_or_resources)
+      else
+        url, options = build_url(api_method, args)
 
-      url.prepend(self.class::ENDPOINT) unless URI(url).scheme
+        raise ArgumentError, ":body parameter was not passed" if !options[:body] && %w(POST PUT PATCH).include?(api_method['httpMethod'])
 
-      # Adopt Google's API erorr handling recommendation here:
-      # https://developers.google.com/drive/manage-uploads#exp-backoff
-      #
-      # In essence, we try 5 times to perform the request. With each subsequent request,
-      # we wait 2^n seconds plus a random number of milliseconds (no greater than 1 second)
-      # until either we receive a successful response, or we run out of attempts.
-      # If the Retry-After header is in the error response, we use whichever happens to be
-      # greater, our calculated wait time, or the value in the Retry-After header.
-      attempt = 0
-      while attempt < 5
-        response = access_token.send(method, url, args)
-        break unless response.status >= 500
-        seconds_to_wait = [((2 ** attempt) + rand), response.headers['Retry-After'].to_i].max
-        attempt += 1
-        puts "#{attempt.ordinalize} request attempt failed. Trying again in #{seconds_to_wait} seconds..."
-        sleep seconds_to_wait
+        send(api_method['mediaUpload'] && args[:media] ? :upload : :request, api_method['httpMethod'].downcase, url, options)
       end
+    end
+
+    private
+      # A really important part of this class. The headers are injected here,
+      # and the body is transformed into a JSON'd string when necessary.
+      # We do exponential back-off for error responses, and return a parsed
+      # response body if present, the full Response object if not.
+      def request(method, url = nil, options = {})
+        options[:headers] = {'Content-Type' => 'application/json'}.merge(options[:headers] || {})
+        options[:body] = options[:body].to_json if options[:body].is_a?(Hash)
 
-      if response.body.present?
-        case format
-        when :json
-          JSON.parse(response.body)
-        when :xml
-          Nokogiri::XML(response.body)
+        # Adopt Google's API erorr handling recommendation here:
+        # https://developers.google.com/drive/handle-errors#implementing_exponential_backoff
+        #
+        # In essence, we try 5 times to perform the request. With each subsequent request,
+        # we wait 2^n seconds plus a random number of milliseconds (no greater than 1 second)
+        # until either we receive a successful response, or we run out of attempts.
+        # If the Retry-After header is in the error response, we use whichever happens to be
+        # greater, our calculated wait time, or the value in the Retry-After header.
+        #
+        # If development_mode is set to true, we only run the request once. This speeds up
+        # development for those using this gem.
+        attempt = 0
+        max_attempts = GoogleAPI.development_mode ? 1 : 5
+        while attempt < max_attempts
+          response = access_token.send(method.to_sym, url, options)
+          seconds_to_wait = [((2 ** attempt) + rand), response.headers['Retry-After'].to_i].max
+          attempt += 1
+          break if response.status < 400 || attempt == max_attempts
+          GoogleAPI.logger.error "Request attempt ##{attempt} to #{url} failed for. Trying again in #{seconds_to_wait} seconds..."
+          sleep seconds_to_wait
         end
-      else
-        response
-      end
-    end
 
-    # Shortcut methods to easily execute a HTTP request with any of the below HTTP verbs.
-    [:get, :post, :put, :patch, :delete].each do |method|
-      define_method method do |url = nil, args = {}|
-        request(method, url, args)
+        response.parsed || response
       end
-    end
 
-    # Build a resumable upload request that then delegates to #post and #put with the correct
-    # headers for each request.
-    #
-    # The initial POST request initiates the upload process, passing the metadata for the file.
-    # The response from the API includes a Location header telling us where to actually send the
-    # file we want uploaded. The subsequent PUT request sends the file itself to the API.
-    def upload(url, object, file_path)
-      object[:mimeType] = MIME::Types.type_for(file_path).first.to_s
-      file = File.read(file_path)
-
-      response = post(build_upload_url(url), body: object, headers: {'X-Upload-Content-Type' => object[:mimeType]})
-      put(response.headers['Location'], body: file, headers: {'Content-Type' => object[:mimeType], 'Content-Length' => file.bytesize.to_s})
-    end
+      # Build a resumable upload request that then makes POST and PUT requests with the correct
+      # headers for each request.
+      #
+      # The initial POST request initiates the upload process, passing the metadata for the file.
+      # The response from the API includes a Location header telling us where to actually send the
+      # media we want uploaded. The subsequent PUT request sends the media itself to the API.
+      def upload(api_method, url, options = {})
+        mime_type = ::MIME::Types.type_for(options[:media]).first.to_s
+        file = File.read(options.delete(:media))
 
-    private
-      # Each class that inherits from this API class can have GDATA_VERSION set as a constant.
-      # This is then passed on to each request if present to dictate which version of Google's
-      # API we intend to use.
-      def version
-        self.class::GDATA_VERSION rescue nil
-      end
+        options[:body][:mimeType] = mime_type
+        options[:headers] = (options[:headers] || {}).merge({'X-Upload-Content-Type' => mime_type})
 
-      # By default we use JSON as the format we pass to Google and get back from Google. To override
-      # this default setting, each class that inherits from this API class can have FORMAT set as
-      # a constant. The only other possible value can be XML.
-      def format
-        raise ArgumentError, "#{self.class} has FORMAT set to #{self.class::FORMAT}, which is not :json or :xml" unless [:json, :xml].include?(self.class::FORMAT)
-        self.class::FORMAT
+        response = request(api_method, url, options)
+
+        options[:body] = file
+        options[:headers].delete('X-Upload-Content-Type')
+        options[:headers].merge!({'Content-Type' => mime_type, 'Content-Length' => file.bytesize.to_s})
+
+        request(:put, response.headers['Location'], options)
       end
 
-      # Build the header hash for the request. If #version is set, we pass that as GData-Version,
-      # and if #format is set, we pass that as Content-Type.
-      def headers
-        headers = {}
-        headers['GData-Version'] = version if version
-        headers['Content-Type'] = case format
-        when :json
-          'application/json'
-        when :xml
-          'application/atom+xml'
+      # Put together the full URL we will send a request to.
+      # First we join the API's base URL with the current method's path, forming the main URL.
+      #
+      # If the method is mediaUpload-enabled (like uploading a file to Google Drive), then we want
+      # to take the path from the resumable upload protocol.
+      #
+      # If not, then, we are going to iterate through each of the parameters for the current method.
+      # When the parameter's location is within the path, we first check that we have had that
+      # option passed, and if so, substitute it in the correct place.
+      # When the parameter's location is a query, we add it to our query parameters hash, provided it is present.
+      # Before returning the URL and remaining options, we have to build the query parameters hash
+      # into a string and append it to the end of the URL.
+      def build_url(api_method, options = {})
+        if api_method['mediaUpload'] && options[:media]
+          # we need to do [1..-1] to remove the prepended slash
+          url = GoogleAPI.discovered_apis[api]['rootUrl'] + api_method['mediaUpload']['protocols']['resumable']['path'][1..-1]
+        else
+          url = GoogleAPI.discovered_apis[api]['baseUrl'] + api_method['path']
+          query_params = []
+          api_method['parameters'].each_with_index do |(param, settings), index|
+            param = param.to_sym
+            case settings['location']
+            when 'path'
+              raise ArgumentError, ":#{param} was not passed" if settings['required'] && !options[param]
+              url.sub!("{#{param}}", options.delete(param).to_s)
+            when 'query'
+              query_params << "#{param}=#{options.delete(param)}" if options[param]
+            end
+          end
+          url += "?#{query_params.join('&')}" if query_params.length > 0
         end
-        return headers
-      end
 
-      def build_upload_url(url)
-        path = URI(self.class::ENDPOINT).path
-        "https://www.googleapis.com/upload#{path}#{url}?uploadType=resumable"
+        [url, options]
       end
 
   end

data/lib/google-api/client.rb

@@ -9,15 +9,19 @@ module GoogleAPI
     def initialize(object)
       @object = object
 
-      raise NoMethodError, "GoogleAPI::Client must be passed an object that is to oauthable. #{object.class.name} is not oauthable." unless object.class.respond_to?(:oauthable)
+      raise NoMethodError, "#{self.class} must be passed an object that is to oauthable. #{object.class.name} is not oauthable." unless object.class.respond_to?(:oauthable)
+      raise ArgumentError, "#{object.class.name} does not appeared to be OAuth2 authenticated. GoogleAPI requires :oauth_access_token, :oauth_request_token, and :oauth_access_token_expires_at to be present." unless object.oauth_hash.values.all?
     end
 
     # Build an AccessToken object from OAuth2. Check if the access token is expired, and if so,
     # refresh it and save the new access token returned from Google.
     def access_token
-      @access_token ||= ::OAuth2::AccessToken.new(client, oauth_hash[:access_token], oauth_hash.except(:access_token))
+      @access_token = ::OAuth2::AccessToken.new(client, object.oauth_hash[:access_token],
+        refresh_token: object.oauth_hash[:refresh_token],
+        expires_at: object.oauth_hash[:expires_at].to_i
+      )
       if @access_token.expired?
-        puts "Access Token expired, refreshing..."
+        GoogleAPI.logger.info "Access Token expired for #{object.class.name}(#{object.id}), refreshing..."
         @access_token = @access_token.refresh!
         object.update_access_token!(@access_token.token)
       end
@@ -25,21 +29,8 @@ module GoogleAPI
       @access_token
     end
 
-    # Build the oauth_hash used to build the AccessToken object above. If any of the values
-    # are nil?, we raise an error and tell the user.
-    def oauth_hash
-      unless @oauth_hash
-        hash = object.oauth_hash.dup
-        hash[:expires_at] = hash[:expires_at].to_i if hash[:expires_at].present?
-        raise ArgumentError, "#{object.class.name} does not appeared to be OAuth2 authenticated. GoogleAPI requires :oauth_access_token, :oauth_request_token, and :oauth_access_token_expires_at to be present." unless hash.values.all?
-      end
-
-      @oauth_hash ||= hash
-    end
-
     # Build the OAuth2::Client object to be used when building an AccessToken.
     def client
-      puts "Creating the OAuth2::Client object..." unless @client
       @client ||= ::OAuth2::Client.new(GoogleAPI.client_id, GoogleAPI.client_secret,
         site: 'https://accounts.google.com',
         token_url: '/o/oauth2/token',
@@ -47,16 +38,25 @@ module GoogleAPI
       )
     end
 
-    # Each API that Google offers us is instantiated within its own method below.
-    # If you want to find all calendars for a user, you would do this:
+    # We build the appropriate API here based on the method name passed to the Client.
+    # For example:
     #
-    #   GoogleAPI::Client.new(User.first).calendar.all
+    #   User.find(1).google.drive
     #
-    # See GoogleAPI::Calendar for more information about the Calendar API.
-    %w(calendar drive).each do |api|
-      define_method api do
-        "GoogleAPI::#{api.capitalize}".constantize.new(access_token)
+    # We will then discover and cache the Google Drive API for future use.
+    # Any methods chained to the resultant API will then be passed along to the
+    # instantiaed class. Read the documentation for GoogleAPI::API#method_missing for
+    # more information.
+    def method_missing(api, *args)
+      unless GoogleAPI.discovered_apis.has_key?(api)
+        GoogleAPI.logger.info "Discovering the #{api} Google API..."
+        response = access_token.get("https://www.googleapis.com/discovery/v1/apis?preferred=true&name=#{api}").parsed['items']
+        super unless response # Raise a NoMethodError if Google's Discovery API does not return a good response
+        discovery_url = response.first['discoveryRestUrl']
+        GoogleAPI.discovered_apis[api] = access_token.get(discovery_url).parsed
       end
+
+      API.new(access_token, api, GoogleAPI.discovered_apis[api]['resources'])
     end
 
   end

data/lib/google-api/oauth2.rb

@@ -0,0 +1,16 @@
+# This can go away once the below commit is released with OAuth2.
+# https://github.com/intridea/oauth2/commit/8dc6feab9927c3fc03b8e0975909a96049a1cbd3
+# Should be in 0.8.1 or 0.9.0
+
+module OAuth2
+  class AccessToken
+
+    # Make a PATCH request with the Access Token
+    #
+    # @see AccessToken#request
+    def patch(path, opts={}, &block)
+      request(:patch, path, opts, &block)
+    end
+
+  end
+end

data/lib/google-api/railtie.rb

@@ -4,7 +4,7 @@
 require 'google-api/active_record_inclusions'
 
 module GoogleAPI
-  class Railtie < Rails::Railtie
+  class Railtie < ::Rails::Railtie
 
     initializer "google_api.configure_rails_initialization" do |app|
       ActiveRecord::Base.send(:include, ActiveRecordInclusions)

data/lib/google-api.rb

@@ -1,24 +1,61 @@
+require 'mime/types'
+require 'oauth2'
+require 'google-api/oauth2'
 require 'google-api/api'
-require 'google-api/api/calendar'
-require 'google-api/api/drive'
 require 'google-api/client'
-require 'google-api/railtie'
+if defined?(::Rails)
+  require 'google-api/railtie'
+else
+  require 'logger'
+end
 
 module GoogleAPI
 
-  # This enables us to easily pass the client_id and client_secret from the Rails
-  # app with a GoogleAPI.configure block. See the README for more information.
+  # This enables us to easily pass the client_id and client_secret with a
+  # GoogleAPI.configure block. See the README for more information.
   # Loosely adapted from Twitter's configuration capabilities.
   # https://github.com/sferik/twitter/blob/v3.6.0/lib/twitter/configurable.rb
   class << self
 
-    attr_accessor :client_id, :client_secret
+    attr_accessor :client_id, :client_secret, :development_mode, :logger
 
+    # Configuration options:
+    #
+    #   development_mode: make it easier to build your application with this API. Default is false
+    #   logger: if this gem is included in a Rails app, we will use the Rails.logger, otherwise, we log to STDOUT
     def configure
       yield self
+
+      raise ArgumentError, "GoogleAPI requires both a :client_id and :client_secret configuration option to be set." unless [client_id, client_secret].all?
+
+      @development_mode ||= false
+      @logger ||= defined?(::Rails) ? Rails.logger : stdout_logger
+
       self
     end
 
+    # An internally used hash to cache the discovered API responses.
+    # Keys could be 'drive', 'calendar', 'contacts', etc.
+    # Values will be a parsed JSON hash.
+    def discovered_apis
+      @discovered_apis ||= {}
+    end
+
+    # The default logger for this API. When we aren't within a Rails app,
+    # we will output log messages to STDOUT.
+    def stdout_logger
+      logger = Logger.new(STDOUT)
+      logger.progname = "google-api"
+      logger
+    end
+
+    # Used primarily within the test suite to reset our GoogleAPI environment for each test.
+    def reset_environment!
+      @development_mode = false
+      @logger = nil
+      @discovered_apis = {}
+    end
+
   end
 
 end

data/spec/fixtures/discovery_drive.json

@@ -0,0 +1,22 @@
+{
+ "kind": "discovery#directoryList",
+ "discoveryVersion": "v1",
+ "items": [
+  {
+   "kind": "discovery#directoryItem",
+   "id": "drive:v2",
+   "name": "drive",
+   "version": "v2",
+   "title": "Drive API",
+   "description": "The API to interact with Drive.",
+   "discoveryRestUrl": "https://www.googleapis.com/discovery/v1/apis/drive/v2/rest",
+   "discoveryLink": "./apis/drive/v2/rest",
+   "icons": {
+    "x16": "https://ssl.gstatic.com/docs/doclist/images/drive_icon_16.png",
+    "x32": "https://ssl.gstatic.com/docs/doclist/images/drive_icon_32.png"
+   },
+   "documentationLink": "https://developers.google.com/drive/",
+   "preferred": true
+  }
+ ]
+}