spark_api 1.5.7 → 1.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d4131f03016f01954473ff13da4f6eaa5b3e449467014e1f0724499749bf017
-  data.tar.gz: 1512fd78baf9b9fa6b62d7be62c9d54b7b4c16fabdec4f114b8c25c785970e46
+  metadata.gz: e315d7b172f1df48cf669a4900fde0367b629dba0fa337b1047d5aeb38c32dfb
+  data.tar.gz: cd034a5ea19d67503c5fca449771fa882a1f0b37b673d3f2259f38db0276a12a
 SHA512:
-  metadata.gz: 16535b943347c4c5118ed263e6e8d18dc46a27a9e79aa15e4cd2c02ccdeec712264132484809aa615949419d3260144763de353caec929b6d26ed7e5d4941803
-  data.tar.gz: 79b6a7b6fb8984045b64ead26347673591c0a6a7075c33dd310ba246047dc7d9c36146d2cef2cff699ab18ef1be0a6e21f8ba1f173316f49f3c87e69c9f712e9
+  metadata.gz: da7b242dbdeb0dac71a5334a6a26d158ad49a8bc0c835b896b754f4ba4d4da87445c50164406863a8ba23d2f5a99ef6f95c0d08b4cf0b53392243012803289ad
+  data.tar.gz: c172948eff245c7ca407fb7a3d73f7634ce43fc1a1f906bdb90a4f73d2b7166eb0f88046beef6f856bab938dc15d4462af6b6150f0059c79e1b27291266d56b0

data/README.md

@@ -10,35 +10,76 @@ Documentation
 
 For further client documentation, please consult our [wiki](https://github.com/sparkapi/spark_api/wiki).
 
-For full information on the API, see [http://sparkplatform.com/docs/overview/api](http://sparkplatform.com/docs/overview/api)
+For full information on the Spark API, see [http://sparkplatform.com/docs/overview/api](http://sparkplatform.com/docs/overview/api). If you would instead like information on the RESO Web API, see [http://sparkplatform.com/docs/reso/overview](http://sparkplatform.com/docs/reso/overview)
 
 
 Installation
 ---------
     gem install spark_api
 
+
+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.
+
+#### [Access Token Authentication](https://github.com/sparkapi/spark_api/wiki/Spark-Authentication) (Preferred)
+Also known as Bearer Token Authentication. If you've been provided a single non-expiring access (bearer) token for the purpose of accessing data on behalf of one or more MLS users, this method of authentication should be used. See "script/access_token_example.rb" for an example. 
+
+#### [OpenId/OAuth2 Combined Flow](https://github.com/sparkapi/spark_api/wiki/Hybrid-Authentication)
+Authorization mode that separates application and user authentication. This mode requires the end user to be redirected to Spark Platform's openid endpoint in a web browser window. 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](https://github.com/sparkapi/spark_api/wiki/OAuth2-Only-Authentication)
+Authorization mode that separates application and user authentication. This mode requires the end user to be redirected to Spark Platform's auth endpoint in a web browser window. 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>.
+
+#### [Spark API Authentication](https://github.com/sparkapi/spark_api/wiki/Spark-Authentication) (Deprecated)
+Usually supplied for a single user, this authentication mode was our old standard, however, is now deprecated in favor of bearer token authentication. See "script/spark_auth_example.rb" for an example. 
+
+
 Usage Examples
 ------------------------
-
+#### Accessing the Spark API (Default)
 ```ruby
 require 'spark_api'
 SparkApi.configure do |config|
   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'
+  config.authentication_mode = SparkApi::Authentication::OAuth2  
+end
+  #Non-expiring bearer token auth. See below if you are using a different authentication method.
+SparkApi.client.session = SparkApi::Authentication::OAuthSession.new({ :access_token => "your_bearer_token_here" })
+puts SparkApi.client.get '/system'
+```
+
+#### Accessing the RESO Web API
+```ruby
+require "spark_api"
+
+# set up session and set the client to hit the RESO API endpoints.
+SparkApi.configure do |config|
+    config.authentication_mode = SparkApi::Authentication::OAuth2
+    config.middleware = :reso_api
 end
-SparkApi.client.get '/my/account'
+  #Non-expiring bearer token auth. See below if you are using a different authentication method.
+SparkApi.client.session = SparkApi::Authentication::OAuthSession.new({ :access_token => "your_access_token_here" })
+
+puts SparkApi.client.get("/Property", {:$top => 10 })
 ```
 
+The examples above utilize access token authentication. For examples using different authentication methods review the wiki and /script folder within this project.
 
 #### 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:
+Included in the gem is an interactive spark_api console to interact with the api in a manner similar to the rails console. Here are a few examples using various auth methods:
 
-    > spark_api --api_key MY_SPARK_API_KEY --api_secret MY_SPARK_API_SECRET
-    SparkApi> SparkApi.client.get '/my/account'
+Access Token Auth:
+
+    > spark_api --oauth2
+    SparkApi:001:0> SparkApi.client.session = SparkApi::Authentication::OAuthSession.new({ :access_token => "your_access_token_here" })
+    SparkApi:002:0> 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. 
+Standard OAuth2 access 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. 
 
     > bundle exec spark_api --oauth2 --client_id my_oauth2_client_id --client_secret my_oauth2_client_secret 
     Loading spark_api gem...
@@ -51,13 +92,18 @@ Using OAuth2 requires different arguments, and is a bit more complicated as it r
     SparkApi:002:0> Account.my.UserType
     "Member"
 
+[Spark Auth (deprecated)](http://sparkplatform.com/docs/authentication/spark_api_authentication):
+
+    > spark_api --api_key MY_SPARK_API_KEY --api_secret MY_SPARK_API_SECRET
+    SparkApi> SparkApi.client.get '/my/account'
+
 You can also provide other options from the command line, see "spark_api -h" for more information.
 
 #### 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.
 
 ```ruby
-SparkApi.client.get     "/listings/#{listing_id}", :_expand => "CustomFields"
+SparkApi.client.get     "/listings", :_expand => "CustomFields", :_filter => "MlsStatus Eq 'Active'", :_limit => 1
 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}"
@@ -81,20 +127,3 @@ JSON Parsing
 --------------
 By default, this gem uses the pure ruby json gem for parsing API responses for cross platform compatibility. Projects that include the yajl-ruby gem will see noticeable speed improvements when installed.
 
-
-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.
-
-#### [Spark API Authentication](https://github.com/sparkapi/spark_api/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](https://github.com/sparkapi/spark_api/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](https://github.com/sparkapi/spark_api/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>.

data/VERSION

@@ -1 +1 @@
-1.5.7
+1.6.1

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

@@ -82,8 +82,8 @@ module SparkApi
         
         def load_file
           yaml = {}
-          begin 
-            yaml = YAML.load(File.open(filename))
+          begin
+            yaml = YAML.respond_to?(:unsafe_load) ? YAML.unsafe_load(File.open(filename)) : YAML.load(File.open(filename))
             yaml = {} if yaml == false
           rescue => e
             puts "no file: #{e.message}"

data/lib/spark_api/configuration/yaml.rb

@@ -16,7 +16,9 @@ module SparkApi
       def load_file(file)
         @file = file
         @name = File.basename(file, ".yml")
-        config = YAML.load(ERB.new(File.read(file)).result)[api_env]
+
+        erb_file = ERB.new(File.read(file)).result
+        config = (YAML.respond_to?(:unsafe_load) ? YAML.unsafe_load(erb_file) : YAML.load(erb_file))[api_env]
         config["oauth2"] == true  ? load_oauth2(config) : load_api_auth(config)
       rescue => e
         SparkApi.logger().error("Unable to load config file #{file}[#{api_env}]")

data/script/access_token_example.rb

@@ -0,0 +1,16 @@
+require "spark_api"
+
+SparkApi.configure do |config|
+  config.endpoint   = 'https://sparkapi.com'
+  config.authentication_mode = SparkApi::Authentication::OAuth2  
+end
+
+  #### COPY/PASTE YOUR ACCESS TOKEN WHERE DESIGNATED BELOW 
+SparkApi.client.session = SparkApi::Authentication::OAuthSession.new({ :access_token => "your_access_token_here" })
+
+client = SparkApi.client
+
+list = client.get '/contacts'
+puts "client: #{list.inspect}"
+list = SparkApi::Models::Contact.get
+puts "model: #{list.inspect}"

data/script/example.rb

@@ -10,12 +10,12 @@ require path + '/spark_api'
 SparkApi.logger.info("Hello!")
 
 SparkApi.configure do |config|
-  config.api_key = "agent_key"
-  config.api_secret = "agent_secret"
-  config.version = "v1"
-  config.endpoint = "https://api.sparkapi.com"
+  config.endpoint   = 'https://sparkapi.com'
+  config.authentication_mode = SparkApi::Authentication::OAuth2  
 end
 
+SparkApi.client.session = SparkApi::Authentication::OAuthSession.new({ :access_token => "your_access_token_here" })
+
 client = SparkApi.client
 
 list = client.get '/contacts'

data/script/reso_middleware_example.rb

@@ -1,8 +1,6 @@
 #!/usr/bin/env ruby
 
-# This script demonstrates how to use the RESO Web API with the Ruby client by pulling listings
-# and replacing encoded field values with their corresponding human-readable values, which are
-# pulled from the XML returned by the RESO metadata endpoint.
+# This script demonstrates how to access the RESO Web API with FBS's Ruby API client.
 
 require "spark_api"
 require "nokogiri"
@@ -12,59 +10,62 @@ SparkApi.configure do |config|
     config.authentication_mode = SparkApi::Authentication::OAuth2
     config.middleware = :reso_api
 end
-
-SparkApi.client.session = SparkApi::Authentication::OAuthSession.new({ :access_token => "OAUTH2_ACCESS_TOKEN" })
+  #### COPY/PASTE YOUR ACCESS TOKEN BELOW
+SparkApi.client.session = SparkApi::Authentication::OAuthSession.new({ :access_token => "your_access_token_here" })
 
 # pull metadata from RESO Web API
-metadata_res = (SparkApi.client.get("/$metadata", {:$ApiUser => "FLEXMLS_TECH_ID"}) )
+metadata_res = SparkApi.client.get("/$metadata")
 metadata_xml = Nokogiri::XML(metadata_res).remove_namespaces!
 
-# make an array of fields which need to be checked for readable values
-fields_to_lookup = []
-metadata_xml.xpath('//Schema/EnumType/@Name').each do |el|
-  fields_to_lookup << el.to_str
-end
+## make an array of fields which need to be checked for readable values
+## API now returns decoded field values. This is no longer necessary
+#fields_to_lookup = []
+#metadata_xml.xpath('//Schema/EnumType/@Name').each do |el|
+#  fields_to_lookup << el.to_str
+#end
 
 # get 25 listings
-listings = (SparkApi.client.get("/Property", {:$top => 25, :$ApiUser => "FLEXMLS_TECH_ID"} ))
-
-listings['value'].each do |listing| # for each listing,
-  fields_to_lookup.each do |field| # go through the array of fields to be checked.
-    if !!listing[field] # when one of the fields that needs to be checked exists in a listing,
-      if listing[field].is_a? String
-        readable = metadata_xml.xpath( # check for readable value to be swapped in
-          "//Schema/
-          EnumType[@Name=\"#{field}\"]/
-          Member[@Name=\"#{listing[field]}\"]/
-          Annotation"
-        ).attr("String")
-
-        # if there is a readable value, swap it in
-        if !!readable
-          listing[field] = readable.to_str
-        end
-
-      elsif listing[field].is_a? Array
-        readable_arr = []
-        listing[field].each do |el|
-          readable = metadata_xml.xpath( # check for readable value to be swapped in
-            "//Schema/
-            EnumType[@Name=\"#{field}\"]/
-            Member[@Name=\"#{el}\"]/
-            Annotation"
-          ).attr("String")
-
-          # assemble a new array with readable values and swap it in
-          if !!readable
-            readable_arr << readable.to_str
-          else
-            readable_arr << el
-          end
-          listing[field] = readable_arr
-        end
-      end
-    end
-  end
-end
-
+listings = SparkApi.client.get("/Property", {:$top => 25 })
 puts listings
+
+## API now returns decoded field values. The code below is no longer needed
+#listings['value'].each do |listing| # for each listing,
+#  fields_to_lookup.each do |field| # go through the array of fields to be checked.
+#    if !!listing[field] # when one of the fields that needs to be checked exists in a listing,
+#      if listing[field].is_a? String
+#        readable = metadata_xml.xpath( # check for readable value to be swapped in
+#          "//Schema/
+#          EnumType[@Name=\"#{field}\"]/
+#          Member[@Name=\"#{listing[field]}\"]/
+#          Annotation"
+#        ).attr("String")
+#
+#        # if there is a readable value, swap it in
+#        if !!readable
+#          listing[field] = readable.to_str
+#        end
+#
+#      elsif listing[field].is_a? Array
+#        readable_arr = []
+#        listing[field].each do |el|
+#          readable = metadata_xml.xpath( # check for readable value to be swapped in
+#            "//Schema/
+#            EnumType[@Name=\"#{field}\"]/
+#            Member[@Name=\"#{el}\"]/
+#            Annotation"
+#          ).attr("String")
+#
+#          # assemble a new array with readable values and swap it in
+#          if !!readable
+#            readable_arr << readable.to_str
+#          else
+#            readable_arr << el
+#          end
+#          listing[field] = readable_arr
+#        end
+#      end
+#    end
+#  end
+#end
+#
+#puts listings

data/script/spark_auth_example.rb

@@ -0,0 +1,26 @@
+#!/usr/bin/env ruby
+require "rubygems"
+
+Bundler.require(:default, "development") if defined?(Bundler)
+
+path = File.expand_path(File.dirname(__FILE__) + "/../lib/")
+$LOAD_PATH.unshift(path) unless $LOAD_PATH.include?(path)
+require path + '/spark_api'
+
+SparkApi.logger.info("Hello!")
+
+  #### COPY/PASTE YOUR API KEY AND SECRET BELOW
+SparkApi.configure do |config|
+  config.api_key = "agent_key"
+  config.api_secret = "agent_secret"
+  config.version = "v1"
+  config.endpoint = "https://api.sparkapi.com"
+end
+
+client = SparkApi.client
+
+list = client.get '/contacts'
+puts "client: #{list.inspect}"
+list = SparkApi::Models::Contact.get
+puts "model: #{list.inspect}"
+

data/spec/spec_helper.rb

@@ -2,10 +2,12 @@ if ENV['COVERAGE'] == "on"
   require 'simplecov'
   require 'simplecov-rcov'
   SimpleCov.formatter = SimpleCov::Formatter::RcovFormatter
-  SimpleCov.start do
-    add_filter '/vendor'
-    add_filter '/spec'
-    add_filter '/test'
+  unless SimpleCov.running   # Hack to prevent starting SimpleCov multiple times  see: https://github.com/simplecov-ruby/simplecov/issues/1003
+    SimpleCov.start do
+      add_filter '/vendor'
+      add_filter '/spec'
+      add_filter '/test'
+    end
   end
 end
 
@@ -21,13 +23,6 @@ require path + '/spark_api'
 
 require 'spark_api'
 
-if ENV['COVERAGE'] == "on"
-  require 'simplecov'
-  require 'simplecov-rcov'
-  SimpleCov.formatter = SimpleCov::Formatter::RcovFormatter
-  SimpleCov.start { add_filter %w(/vendor /spec /test) }
-end
-
 FileUtils.mkdir 'log' unless File.exists? 'log'
 
 module SparkApi
@@ -51,7 +46,7 @@ end
 
 # Requires supporting ruby files with custom matchers and macros, etc,
 # # in spec/support/ and its subdirectories.
-Dir[File.expand_path(File.join(File.dirname(__FILE__),'support','**','*.rb'))].each {|f| require f}
+Dir[File.expand_path(File.join(File.dirname(__FILE__), 'support', '**', '*.rb'))].each { |f| require f }
 
 RSpec.configure do |config|
 
@@ -66,6 +61,6 @@ RSpec.configure do |config|
   config.color = true
 end
 
-def jruby? 
+def jruby?
   RUBY_PLATFORM == "java"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: spark_api
 version: !ruby/object:Gem::Version
-  version: 1.5.7
+  version: 1.6.1
 platform: ruby
 authors:
 - Brandon Hornseth
@@ -327,6 +327,7 @@ files:
 - lib/spark_api/reso_faraday_middleware.rb
 - lib/spark_api/response.rb
 - lib/spark_api/version.rb
+- script/access_token_example.rb
 - script/bootstrap
 - script/ci_build
 - script/combined_flow_example.rb
@@ -335,6 +336,7 @@ files:
 - script/oauth2_example.rb
 - script/release
 - script/reso_middleware_example.rb
+- script/spark_auth_example.rb
 - spec/fixtures/accounts/all.json
 - spec/fixtures/accounts/my.json
 - spec/fixtures/accounts/my_portal.json