spark_api 1.1.2 → 1.2.0

data/History.txt

@@ -1,3 +1,17 @@
+== v1.2.0 2012-11-14
+* SSL verification enabled by default
+* Sparkbar token access support
+* Fixed oauth2 CLI usage
+* Model behaviors for CRUD operations
+* Dirty module to help manage dirty attributes for updating a model
+* Removed nonsensical "all" method for finder models
+* ApiUser support for OAuth2 flow
+* Subscriptions models
+* Single session OAuth2 support
+* Update RecipientIds attribute on subscribe/unsubscribe
+* Restrict API wrapped json post data for hashes that have content
+* Fix sorting on nils in accounts model
+* Pluralize module
 == v1.1.0 2012-08-07
 * Upgraded faraday and other gems, cleand up the middleware
 == v1.0.4 2012-07-26

data/README.md

@@ -5,6 +5,9 @@ A Ruby wrapper for the Spark REST API. Loosely based on ActiveResource to provid
 
 Documentation
 -------------
+
+For further client documentation, please consult our [wiki](wiki).
+
 For full information on the API, see [http://sparkplatform.com/docs/overview/api](http://sparkplatform.com/docs/overview/api)
 
 
@@ -14,268 +17,74 @@ Installation
 
 Usage Examples
 ------------------------
-
-#### Ruby Script: OpenId/OAuth2 Combined Flow
-    # initialize the gem with your key/secret.
-    # See also: script/combined_flow_example.rb
-    # api_key, api_secret, and callback are all required.
-    # The following options are required:
-    #  - api_key: Your client key
-    #  - api_secret: Your client secret
-    #  - callback: Your redirect_uri, which the end user will be redirected
-    #              to after authorizing your application to access their data.
-    #  - auth_endpoint: The URI to redirect the user's web browser to, in order for them to
-    #                   authorize your application to access their data.
-    # other options and their defaults:
-    #  - endpoint:   'https://api.sparkapi.com'
-    #  - version:    'v1'
-    #  - ssl:        true
-    #  - user_agent: 'Spark API Ruby Gem'
-    SparkApi.configure do |config|
-      config.authentication_mode = SparkApi::Authentication::OpenIdOAuth2Hybrid
-      config.api_key      = "YOUR_CLIENT_ID"
-      config.api_secret   = "YOUR_CLIENT_SECRET"
-      config.callback     = "YOUR_REDIRECT_URI"
-      config.auth_endpoint = "https://developers.sparkplatform.com/openid"
-      config.endpoint   = 'https://developers.sparkapi.com'
-    end
-
-    # Code is retrieved from the method: SparkApi.client.authenticator.authorization_url
-    # See script/combined_flow_example.rb for more details.
-
-
-    SparkApi.client.oauth2_provider.code = "CODE_FROM_ABOVE_URI"
-    SparkApi.client.authenticate
-
-    # Alternatively, if you've already received an access token, you may
-    # do the following instead of the above two lines:
-    # SparkApi.client.session = SparkApi::Authentication::OAuthSession.new "access_token"=> "ACCESS_TOKEN", 
-    #                            "refresh_token" => "REFRESH_TOKEN", "expires_in" => 86400
-
-    # mixin the models so you can use them without prefix
-    include SparkApi::Models
-
-    # Grab your listings!
-    my_listings = Listing.my()
-
-#### Ruby Script: OAuth 2
-    # initialize the gem with your OAuth 2 key/secret.
-    # See also: script/oauth2_example.rb
-    # api_key, api_secret, and callback are all required.
-    # The following options are required:
-    #  - api_key: Your OAuth 2 client key
-    #  - api_secret: Your OAuth 2 client secret
-    #  - callback: Your OAuth 2 redirect_uri, which the end user will be redirected
-    #              to after authorizing your application to access their data.
-    #  - auth_endpoint: The URI to redirect the user's web browser to, in order for them to
-    #                   authorize your application to access their data.
-    # other options and their defaults:
-    #  - endpoint:   'https://api.sparkapi.com'
-    #  - version:    'v1'
-    #  - ssl:        true
-    #  - user_agent: 'Spark API Ruby Gem'
     SparkApi.configure do |config|
-      config.authentication_mode = SparkApi::Authentication::OAuth2
-      config.api_key      = "YOUR_CLIENT_ID"
-      config.api_secret   = "YOUR_CLIENT_SECRET"
-      config.callback     = "YOUR_REDIRECT_URI"
-      config.auth_endpoint = "https://developers.sparkplatform.com/oauth2"
-      config.endpoint   = 'https://developers.sparkapi.com'
+      config.endpoint   = 'https://sparkapi.com'
+      # Using Spark API Authentication, refer to the Authentication documentation for OAuth2
+      config.api_key    = 'MY_SPARK_API_KEY'
+      config.api_secret = 'MY_SPARK_API_SECRET'
     end
-
-    # Code is retrieved from the method. SparkApi.client.authenticator.authorization_url
-    # See script/oauth2_example.rb for more details.
+    SparkApi.client.get '/my/account'
 
 
-    SparkApi.client.oauth2_provider.code = "CODE_FROM_ABOVE_URI"
-    SparkApi.client.authenticate
-
-    # Alternatively, if you've already received an access token, you may
-    # do the following instead of the above two lines:
-    #SparkApi.client.session = SparkApi::Authentication::OAuthSession.new "access_token"=> "ACCESS_TOKEN", 
-    #                           "refresh_token" => "REFRESH_TOKEN", "expires_in" => 86400
-
-    # mixin the models so you can use them without prefix
-    include SparkApi::Models
+#### Interactive Console
+Included in the gem is an interactive spark_api console to interact with the api in a manner similar to the rails console. Below is a brief example of interacting with the console:
 
-    # Grab your listings!
-    my_listings = Listing.my()
+    > spark_api --api_key MY_SPARK_API_KEY --api_secret MY_SPARK_API_SECRET
+    SparkApi> SparkApi.client.get '/my/account'
 
+Using OAuth2 requires different arguments, and is a bit more complicated as it requires a step for logging in through the browser to gain access to the access code for a client_id. 
 
-#### Ruby Script: OpenId Only
-    # initialize the gem with your key/secret.
-    # api_key, api_secret, and callback are all required.
-    # The following options are required:
-    #  - api_key: Your client key
-    #  - api_secret: Your client secret
-    #  - callback: Your redirect_uri, which the end user will be redirected
-    #              to after authorizing your application to access their data.
-    #  - auth_endpoint: The URI to redirect the user's web browser to, in order for them to
-    #                   authorize your application to access their data.
-    # other options and their defaults:
-    #  - user_agent: 'Spark API Ruby Gem'
-    SparkApi.configure do |config|
-      config.authentication_mode = SparkApi::Authentication::OpenId
-      config.api_key      = "YOUR_CLIENT_ID"
-      config.api_secret   = "YOUR_CLIENT_SECRET"
-      config.callback     = "YOUR_REDIRECT_URI"
-      config.auth_endpoint = "https://developers.sparkplatform.com/openid"
-    end
+    > bundle exec spark_api --oauth2 --client_id my_oauth2_client_id --client_secret my_oauth2_client_secret 
+    Loading spark_api gem...
+    SparkApi:001:0> Account.my.Name
+    Missing OAuth2 session, redirecting...
+    Please visit https://sparkplatform.com/oauth2?client_id=my_oauth2_client_id&response_type=code&redirect_uri=https%3A%2F%2Fsparkplatform.com%2Foauth2%2Fcallback, login as a user, and paste the authorization code here:
+    Authorization code?
+    9zsrc7jk7m4x7r4kers8n6sp5
+    "Demo User"
+    SparkApi:002:0> Account.my.UserType
+    "Member"
 
-    # Code is retrieved from the method: 
-    # See script/combined_flow_example.rb for more details.
-    # Optionally, additional a GET parameters can be supplied as a hash to
-    # authorization_url.
-    # SparkApi.client.authenticator.authorization_url
+You can also provide other options from the command line, see "spark_api -h" for more information.
 
-    # That's it! No API Access is available when using OpenID alone.
+#### HTTP Interface
+The base client provides a bare bones HTTP interface for working with the RESTful Spark API. This is basically a stylized curl interface that handles authentication, error handling, and processes JSON results as Ruby Hashes.
 
+    SparkApi.client.get     "/listings/#{listing_id}", :_expand => "CustomFields"
+    SparkApi.client.post    "/listings/#{listing_id}/photos", photo_body_hash
+    SparkApi.client.put     "/listings/#{listing_id}/photos/#{photo_id}", updated_photo_name_hash
+    SparkApi.client.delete  "/listings/#{listing_id}/photos/#{photo_id}"
 
-#### Ruby Script
-    # initialize the gem with your key/secret
-    # api_key and _api_secret are the only required settings
-    # other options and their defaults:
-    #  - endpoint:   'https://api.sparkapi.com'
-    #  - version:    'v1'
-    #  - ssl:         false
-    #  - user_agent: 'Spark API Ruby Gem'
-    SparkApi.configure do |config|
-        config.endpoint   = 'https://developers.sparkapi.com'
-        config.api_key    = 'my_api_key'
-        config.api_secret = 'my_api_secret'
-    end
+#### [API Models](wiki/API-Models)
+The client also provides ActiveModelesque interface for working with the api responses. Notably, the models use finder methods for searching, and similar instanciation and persistence also on supported services.
 
-    # mixin the models so you can use them without prefix
+    # Tip: mixin the models so you can use them without namespaces
     include SparkApi::Models
-
-    # Grab your listings!
-    my_listings = Listing.my()
-
-
-#### Interactive Console
-Included in the gem is a simple setup script to run the client in IRB.  To use it, first create the file called _.spark_api_testing_ filling in the credentials for your account.
-
-    API_USER="12345678901234567890123456" # 26-digit identifier of an API user
-    API_ENDPOINT="https://developers.sparkapi.com"
-    API_KEY="my_api_key"
-    API_SECRET="my_api_secret"
-
-    export API_USER API_ENDPOINT API_KEY API_SECRET
-
-Now, to run with this setup, run the following from the command line:
-
-    > source .spark_api_testing
-    > spark_api
-    SparkApi> SparkApi.client.get '/my/account'
-
-You can also provide these options from the command line, see "spark_api -h" for more information
+    listings = Listing.find(:all, :_filter => "ListPrice Gt 150000.0 And ListPrice Lt 200000.0", :_orderby => "-ListPrice")
+    puts "Top list price: $%.2f" % listings.first.ListPrice
+    # Top list price: $199999.99
+    puts Account.find(:first, :_filter => "UserType Eq 'Member' And Name Eq 'John*'").Name
+    # John Doe
 
 
 Authentication Types
 --------------
 Authentication is handled transparently by the request framework in the gem, so you should never need to manually make an authentication request.  More than one mode of authentication is supported, so the client needs to be configured accordingly.
 
-#### API Authentication (Default)
+#### [Spark API Authentication](wiki/Spark-Authentication) (Default)
 Usually supplied for a single user, this authentication mode is the simplest, and is setup as the default.  The example usage above demonstrates how to get started using this authentication mode.
 
-#### OpenId/OAuth2 Combined Flow (Preferred)
+#### [OpenId/OAuth2 Combined Flow](wiki/Hybrid-Authentication) (Preferred)
 Authorization mode the separates application and user authentication.  This mode requires the end user to be redirected to Spark Platform's openid endpoint.  See "script/combined_flow_example.rb" for an example.
 
 Read more about Spark Platform's combined flow <a href="http://sparkplatform.com/docs/authentication/openid_oauth2_authentication">here</a>.
 
-#### OAuth2 Authorization
+#### [OAuth2 Authorization](wiki/OAuth2-Only-Authentication)
 Authorization mode the separates application and user authentication.  This mode requires the end user to be redirected to Spark Platform's auth endpoint.  See "script/oauth2_example.rb" for an example.
 
 Read more about Spark Platform's OAuth 2 flow <a href="http://sparkplatform.com/docs/authentication/oauth2_authentication">here</a>.
 
-#### OpenId Authentication
+#### [OpenId Authentication](wiki/OpenId-Only-Authentication)
 There is also the option to only access a user's Spark Platform identity without accessing any data (e.g. listings, contacts, etc.).  In circumstances where you ONLY with to authenticate users through the Spark Platform, but do not have a use case to access any of their data, consider the OpenId authentication flow in lieu of API Authentication or the Combined flow.
 
 Read more about Spark Platform's OpenId flow <a href="http://sparkplatform.com/docs/authentication/openid_authentication">here</a>.
-
-Error Codes
----------------------
-<table>
-  <thead>
-    <tr>
-      <th>HTTP Code</th>
-      <th>Spark API Error Code</th>
-      <th>Exception Raised</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td><tt>401</tt></td>
-      <td><tt>1000</tt></td>
-      <td><tt></tt></td>
-      <td>Invalid API Key and/or Request signed improperly</td>
-    </tr>
-    <tr>
-      <td><tt>401</tt></td>
-      <td><tt>1010</tt></td>
-      <td><tt></tt></td>
-      <td>API key is disabled</td>
-    </tr>
-    <tr>
-      <td><tt>403</tt></td>
-      <td><tt>1015</tt></td>
-      <td><tt></tt></td>
-      <td><tt>ApiUser</tt> must be supplied, or the provided key does not have access to the supplied user</td>
-    </tr>
-    <tr>
-      <td><tt>401</tt></td>
-      <td><tt>1020</tt></td>
-      <td><tt></tt></td>
-      <td>Session token has expired</td>
-    </tr>
-    <tr>
-      <td><tt>403</tt></td>
-      <td><tt>1030</tt></td>
-      <td><tt></tt></td>
-      <td>SSL required for this type of request</td>
-    </tr>
-    <tr>
-      <td><tt>400</tt></td>
-      <td><tt>1035</tt></td>
-      <td><tt></tt></td>
-      <td>POST data not supplied as valid JSON. Issued if the <tt>Content-Type</tt> header is not <tt>application/json/</tt> and/or if the POST data is not in valid JSON format.</td>
-    </tr>
-    <tr>
-      <td><tt>400</tt></td>
-      <td><tt>1040</tt></td>
-      <td><tt></tt></td>
-      <td>The <tt>_filter</tt> syntax was invalid or a specified field to search on does not exist</td>
-    </tr>
-    <tr>
-      <td><tt>400</tt></td>
-      <td><tt>1050</tt></td>
-      <td><tt></tt></td>
-      <td>(message varies) A required parameter was not provided</td>
-    </tr>
-    <tr>
-      <td><tt>400</tt></td>
-      <td><tt>1053</tt></td>
-      <td><tt></tt></td>
-      <td>(message varies) A parameter was provided but does not adhere to constraints</td>
-    </tr>
-    <tr>
-      <td><tt>409</tt></td>
-      <td><tt>1055</tt></td>
-      <td><tt></tt></td>
-      <td>(message varies)Issued when a write is requested that will conflict with existing data. For example, adding a new contact with an e-mail that already exists.</td>
-    </tr>
-    <tr>
-      <td><tt>403</tt></td>
-      <td><tt>1500</tt></td>
-      <td><tt></tt></td>
-      <td>The resource is not available at the current API key's service level. For example, this error applies if a user attempts to access the IDX Links API via a free API key. </td>
-    </tr>
-    <tr>
-      <td><tt>503</tt></td>
-      <td><tt>1550</tt></td>
-      <td><tt></tt></td>
-      <td>Over rate limit</td>
-  </tbody>
-</table>
-

data/VERSION

@@ -1 +1 @@
-1.1.2
+1.2.0

data/lib/spark_api.rb

@@ -3,6 +3,7 @@ require 'logger'
 require 'multi_json'
 
 require 'spark_api/version'
+require 'spark_api/errors'
 require 'spark_api/configuration'
 require 'spark_api/multi_client'
 require 'spark_api/authentication'

data/lib/spark_api/authentication/oauth2.rb

@@ -43,6 +43,7 @@ module SparkApi
         escaped_path = URI.escape(path)
         connection = @client.connection(true)  # SSL Only!
         connection.headers.merge!(self.auth_header)
+        options.merge!(:ApiUser => "#{@client.api_user}") unless @client.api_user.nil?
         parameter_string = options.size > 0 ? "?#{build_url_parameters(options)}" : ""
         request_path = "#{escaped_path}#{parameter_string}"
         SparkApi.logger.debug("Request: #{request_path}")
@@ -67,19 +68,42 @@ module SparkApi
         }
         "#{@provider.authorization_uri}?#{build_url_parameters(params)}"
       end
-            
+      
+      # Create a sparkbar token based on the current user's access token
+      def sparkbar_token()
+        raise ClientError, "OAuth2Provider must configure the sparkbar_uri to use sparkbar tokens" if provider.sparkbar_uri.nil?
+        SparkApi.logger.debug("[sparkbar] create token to #{provider.sparkbar_uri}")
+        uri = URI.parse(provider.sparkbar_uri)
+        request_path = "#{uri.path}"
+        
+        SparkApi.logger.info("[sparkbar] create token to #{request_path}, #{session.access_token.inspect}")
+        response = sparkbar_connection("#{uri.scheme}://#{uri.host}").post(request_path, "access_token=#{session.access_token}").body
+        token = response["token"]
+        SparkApi.logger.debug("[sparkbar] New token created #{token}")
+        token
+      end
+      
       protected
       
+      attr_reader :provider, :client
+      
       def auth_header
         {"Authorization"=> "OAuth #{session.access_token}"}
       end
       
-      def provider
-        @provider
-      end
-      def client
-        @client
-      end
+      # Faraday handle to the sparkbar
+      def sparkbar_connection(endpoint)
+        opts = {
+          :headers => client.headers
+        }
+        opts[:headers].delete(:content_type)
+        opts[:ssl] = {:verify => false } unless @client.ssl_verify
+        opts[:url] = endpoint       
+        conn = Faraday::Connection.new(opts) do |conn|
+          conn.response :sparkbar_impl
+          conn.adapter Faraday.default_adapter
+        end
+      end        
 
     end
 
@@ -142,16 +166,21 @@ module SparkApi
       end
       #  Is the user session token expired?
       def expired?
+        return false if @expires_in.nil?
         @start_time + Rational(@expires_in - @refresh_timeout, 86400) < DateTime.now
       end
       
       def to_json(*a)
+        to_hash.to_json(*a)
+      end
+      
+      def to_hash
         hash = {}
         SESSION_ATTRIBUTES.each do |k|
           value = self.send(k)
           hash[k.to_s] = value unless value.nil?
         end
-        hash.to_json(*a)
+        hash 
       end
     end
     
@@ -222,8 +251,9 @@ module SparkApi
       require 'spark_api/authentication/oauth2_impl/grant_type_refresh'
       require 'spark_api/authentication/oauth2_impl/grant_type_code'
       require 'spark_api/authentication/oauth2_impl/grant_type_password'
-      require 'spark_api/authentication/oauth2_impl/password_provider'
+      require 'spark_api/authentication/oauth2_impl/cli_provider'
       require 'spark_api/authentication/oauth2_impl/simple_provider'
+      require 'spark_api/authentication/oauth2_impl/single_session_provider'
       
       # Loads a provider class from a string
       def self.load_provider(string, args={})

data/lib/spark_api/authentication/oauth2_impl/cli_provider.rb

@@ -0,0 +1,96 @@
+require "highline/import"
+
+module SparkApi
+  module Authentication
+    module OAuth2Impl
+      class CLIProvider < SparkApi::Authentication::BaseOAuth2Provider
+        SESSION_FILE = '.spark_api_oauth2'
+        
+        def initialize(credentials)
+          super(credentials)
+          @grant_type = :password
+          @persistent_sessions = false
+          @session_alias = "default"
+        end
+        
+        attr_accessor :persistent_sessions, :session_alias
+
+        def redirect(url)
+          puts "Missing OAuth2 session, redirecting..."
+          puts "Please visit #{url}, login as a user, and paste the authorization code here:"
+          self.code = ask("Authorization code?") do |q|
+            q.whitespace = :strip_and_collapse
+            q.validate = /^\w+$/
+          end
+        end
+                
+        def load_session()
+          @session ||= load_persistent_session
+        end
+      
+        def save_session(session)
+          @session = session
+          save_persistent_session
+        end
+      
+        def destroy_session
+          destroy_persistent_session
+          @session = nil
+        end
+      
+        def persistent_sessions?
+          persistent_sessions == true
+        end
+        
+        private 
+        
+        def load_persistent_session
+          return nil unless persistent_sessions?
+          s = load_file[session_key]["session"]
+          OAuthSession.new(s)
+        rescue => e
+          puts "no file: #{e.message}"
+        end
+
+        def save_persistent_session
+          return unless persistent_sessions? && !@session.nil?
+          yaml = load_file
+          unless yaml.include? session_key
+            yaml[session_key] = {}
+            yaml[session_key]["created"] = Time.now   
+          end
+          yaml[session_key]["session"] = @session.to_hash
+          yaml[session_key]["modified"] = Time.now   
+          File.open(filename, "w") {|f| f.write(yaml.to_yaml) }
+        end
+        
+        def session_key
+          "#{client_id}_#{session_alias}"
+        end
+        
+        def destroy_persistent_session
+          return unless persistent_sessions?
+          yaml = load_file
+          return unless yaml.include? session_key 
+          yaml[session_key].delete("session")
+          File.open(filename, "w") {|f| f.write(yaml.to_yaml) }
+        end
+        
+        def filename
+          ENV['HOME'] + "/" + SESSION_FILE
+        end
+        
+        def load_file
+          yaml = {}
+          begin 
+            yaml = YAML.load(File.open(filename))
+            yaml = {} if yaml == false
+          rescue => e
+            puts "no file: #{e.message}"
+          end
+          yaml
+        end
+      end
+    end
+  end
+end