3scale_client 2.3.3 → 2.3.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6f95988b20e7b5a97d35e78533ebcf14c1fbbe79
+  data.tar.gz: c53f311c11d7026ebd7209623623ae7647c17826
+SHA512:
+  metadata.gz: 3f1952038035863de0ee38e63eff23f16f32bdb2d779ada36193b9f1ea204331743c99fb6c9d8004f8f9fe8cae27dc1905d4f9bbcb1b28fd796e8e32ee9bfe48
+  data.tar.gz: a8f67924fb05935f4113102b41fcb321fbec2fca212ff2a5bab234b12cb3264e3e05a7d43b947b1bdccadf379490deb6daf07f7e6fb270093a6ccc5b470b2798

data/.travis.yml

@@ -1,6 +1,5 @@
 language: ruby
 rvm:
-  - 1.9.3
-  - 2.0.0
-  - jruby
-  - rbx-19mode
+  - '1.9.3'
+  - '2.0.0'
+  - 'jruby'

data/README.md

@@ -0,0 +1,237 @@
+# Rubygem for 3scale Web Service Management API
+
+
+[<img src="https://secure.travis-ci.org/3scale/3scale_ws_api_for_ruby.png?branch=master" alt="Build Status" />](http://travis-ci.org/3scale/3scale_ws_api_for_ruby)
+
+3scale is an API Infrastructure service which handles API Keys, Rate Limiting, Analytics, Billing Payments and Developer Management. Includes a configurable API dashboard and developer portal CMS. More product stuff at http://www.3scale.net/, support information at http://support.3scale.net/.
+
+### Tutorials
+Plugin Setup: https://support.3scale.net/howtos/api-configuration/plugin-setup  
+Rate Limiting: https://support.3scale.net/howtos/basics/provision-rate-limits  
+Analytics Setup: https://support.3scale.net/quickstarts/3scale-api-analytics  
+
+## Installation
+
+This library is distributed as a gem:
+```sh
+gem install 3scale_client
+```
+Or alternatively, download the source code from github:
+http://github.com/3scale/3scale_ws_api_for_ruby
+
+If you are using Bundler, please add this to your Gemfile:
+
+```ruby
+gem '3scale_client'
+```
+and do a bundle install.
+
+If you are using Rails' config.gems, put this into your config/environment.rb
+
+```ruby
+config.gem '3scale_client'
+```
+Otherwise, require the gem in whatever way is natural to your framework of choice.
+
+## Usage
+
+First, create an instance of the client, giving it your provider API key:
+
+```ruby
+client = ThreeScale::Client.new(:provider_key => "your provider key")
+```
+Because the object is stateless, you can create just one and store it globally.
+
+### Authrep
+
+Authrep is a 'one-shot' operation to authorize an application and report the associated transaction at the same time.
+The main difference between this call and the regular authorize call is that usage will be reported if the authorization is successful. Read more about authrep at the [active docs page on the 3scale's support site](https://support.3scale.net/reference/activedocs#operation/66)
+
+You can make request to this backend operation like this:
+
+```ruby
+response = client.authrep(:app_id => "the app id", :app_key => "the app key")
+```
+
+Then call the +success?+ method on the returned object to see if the authorization was
+successful.
+
+```ruby
+if response.success?
+  # All fine, the usage will be reported automatically. Proceeed.
+else
+  # Something's wrong with this application.
+end
+```
+
+The example is using the app_id authentication pattern, but you can also use other patterns.
+
+#### A rails example
+
+
+```ruby
+class ApplicationController < ActionController
+  # Call the authenticate method on each request to the API
+  before_filter :authenticate
+        
+  # You only need to instantiate a new Client once and store it as a global variable
+  # You should store your provider key in the environment because this key is secret!
+  def create_client
+    @@threescale_client ||= ThreeScale::Client.new(:provider_key => ENV['PROVIDER_KEY'])    
+  end
+        
+  # To record usage, create a new metric in your application plan. You will use the 
+  # "system name" that you specifed on the metric/method to pass in as the key to the usage hash. 
+  # The key needs to be a symbol. 
+  # A way to pass the metric is to add a parameter that will pass the name of the metric/method along
+  def authenticate
+    response = create_client.authrep(:app_id => params["app_id"], 
+                                     :app_key => params["app_key"],
+                                     :usage => { params[:metric].to_sym => 1 }
+    if response.success?
+      return true
+      # All fine, the usage will be reported automatically. Proceeed.
+    else
+      # Something's wrong with this application.
+      puts "#{response.error_message}"
+      # raise error
+    end
+  end
+end
+```
+
+### Using Varnish to speed up things
+
+3scale provides a [varnish module](https://github.com/3scale/libvmod-3scale) to cache the responses of its backend to help you achieve a close to zero latency. Go and install the module and [configure it the easy way](https://github.com/3scale/libvmod-3scale/blob/master/vcl/default_3scale_simple.vcl)
+
+When that's done all you have to do is to initialize your 3scale client pointing to the location of your varnish, by passing the host parameter to it, like this:
+
+```ruby
+client = ThreeScale::Client.new(:provider_key => "your provider key", :host => "your.varnish.net:8080")
+```
+
+that's it, your API should now be authorized and reported for you, and all that at full speed.
+
+### Authorize
+
+To authorize an application, call the +authorize+ method passing it the application's id and
+optionally a key:
+
+```ruby
+response = client.authorize(:app_id => "the app id", :app_key => "the app key")
+```
+
+Then call the +success?+ method on the returned object to see if the authorization was
+successful.
+
+```ruby
+if response.success?
+  # All fine, the usage will be reported automatically. Proceeed.
+else
+  # Something's wrong with this application.
+end
+```
+
+If both provider key and app id are valid, the response object contains additional
+information about the status of the application:
+
+```ruby
+# Returns the name of the plan the application is signed up to.
+response.plan
+```
+
+If the plan has defined usage limits, the response contains details about the usage broken
+down by the metrics and usage limit periods.
+
+```ruby
+# The usage_reports array contains one element per each usage limit defined on the plan.
+usage_report = response.usage_reports[0]
+
+# The metric
+usage_report.metric # "hits"
+
+# The period the limit applies to
+usage_report.period        # :day
+usage_report.period_start  # "Wed Apr 28 00:00:00 +0200 2010"
+usage_report.period_end    # "Wed Apr 28 23:59:59 +0200 2010"
+
+# The current value the application already consumed in the period
+usage_report.current_value # 8032
+
+# The maximal value allowed by the limit in the period
+usage_report.max_value     # 10000
+
+# If the limit is exceeded, this will be true, otherwise false:
+usage_report.exceeded?     # false
+```
+
+If the authorization failed, the +error_code+ returns system error code and +error_message+
+human readable error description:
+
+```ruby
+response.error_code    # "usage_limits_exceeded"
+response.error_message # "Usage limits are exceeded"
+```
+
+### OAuth Authorize
+
+To authorize an application with OAuth, call the +oauth_authorize+ method passing it the application's id.
+
+```ruby
+response = client.oauth_authorize(:app_id => "the app id")
+```
+
+If the authorization is successful, the response will contain the +app_key+ and +redirect_url+ defined for this application:
+
+```ruby
+response.app_key
+response.redirect_url
+```
+
+### Report
+
+To report usage, use the +report+ method. You can report multiple transaction at the same time:
+
+```ruby
+response = client.report({:app_id => "first app id",  :usage => {'hits' => 1}},
+                         {:app_id => "second app id", :usage => {'hits' => 1}})
+```
+
+The :app_id and :usage parameters are required. Additionaly, you can specify a timestamp
+of transaction:
+
+```ruby
+response = client.report({:app_id => "app id", :usage => {'hits' => 1},
+                          :timestamp => Time.local(2010, 4, 28, 12, 36)})
+```
+
+The timestamp can be either a Time object (from ruby's standard library) or something that
+"quacks" like it (for example, the ActiveSupport::TimeWithZone from Rails) or a string. The
+string has to be in a format parseable by the Time.parse method. For example:
+
+```ruby
+"2010-04-28 12:38:33 +0200"
+```
+
+If the timestamp is not in UTC, you have to specify a time offset. That's the "+0200"
+(two hours ahead of the Universal Coordinate Time) in the example abowe.
+
+Then call the +success?+ method on the returned response object to see if the report was
+successful.
+
+```ruby
+  if response.success?
+    # All OK.
+  else
+    # There was an error.
+  end
+```
+
+In case of error, the +error_code+ returns system error code and +error_message+
+human readable error description:
+
+```ruby
+response.error_code    # "provider_key_invalid"
+response.error_message # "provider key \"foo\" is invalid"
+```  
+  

data/lib/3scale/authorize_response.rb

@@ -10,6 +10,7 @@ module ThreeScale
     attr_accessor :plan
     attr_accessor :app_key
     attr_accessor :redirect_url
+    attr_accessor :service_id
 
     class UsageReport
       attr_reader :metric
@@ -42,4 +43,4 @@ module ThreeScale
       @usage_reports << UsageReport.new(options)
     end
   end
-end
+end

data/lib/3scale/client.rb

@@ -158,9 +158,10 @@ module ThreeScale
     #
     # Hash with options:
     #
-    #   app_id::  id of the application to authorize. This is required.
-    #   app_key:: secret key assigned to the application. Required only if application has
-    #             a key defined.
+    #   app_id::     id of the application to authorize. This is required.
+    #   app_key::    secret key assigned to the application. Required only if application has
+    #                a key defined.
+    #   service_id:: id of the service (required if you have more than one service)
     #
     # == Return
     #
@@ -182,10 +183,7 @@ module ThreeScale
     #   end
     #
     def authorize(options)
-      path = "/transactions/authorize.xml" +
-        "?provider_key=#{CGI.escape(provider_key)}" +
-        "&app_id=#{CGI.escape(options[:app_id].to_s)}"
-        path += "&app_key=#{CGI.escape(options[:app_key])}" if options[:app_key]
+      path = "/transactions/authorize.xml" + options_to_params(options, ALL_PARAMS)
 
       uri = URI.parse("http://#{host}#{path}")
       http_response = Net::HTTP.get_response(uri)
@@ -207,6 +205,7 @@ module ThreeScale
     # Hash with options:
     #
     #   app_id::  id of the application to authorize. This is required.
+    #   service_id:: id of the service (required if you have more than one service)
     #
     # == Return
     #
@@ -231,11 +230,7 @@ module ThreeScale
     #   end
     #
     def oauth_authorize(options)
-      path = "/transactions/oauth_authorize.xml" +
-        "?provider_key=#{CGI.escape(provider_key)}" +
-        "&app_id=#{CGI.escape(options[:app_id].to_s)}"
-        path += "&app_key=#{CGI.escape(options[:app_key])}" if options[:app_key]
-      path += "&redirect_url=#{CGI.escape(options[:redirect_url])}" if options[:redirect_url]
+      path = "/transactions/oauth_authorize.xml" + options_to_params(options, OAUTH_PARAMS)
 
       uri = URI.parse("http://#{host}#{path}")
       http_response = Net::HTTP.get_response(uri)
@@ -252,6 +247,23 @@ module ThreeScale
 
     private
 
+    OAUTH_PARAMS = [:app_id, :app_key, :service_id, :redirect_url]
+    ALL_PARAMS = [:user_key, :app_id, :app_key, :service_id, :redirect_url]
+
+    def options_to_params(options, allowed_keys)
+      params = { :provider_key  => provider_key }
+
+      allowed_keys.each do |key|
+        params[key] = options[key] if options.has_key?(key)
+      end
+
+      tuples = params.map do |key, value|
+        "#{key}=#{CGI.escape(value.to_s)}"
+      end
+
+      '?' + tuples.join('&')
+    end
+
     def encode_transactions(transactions)
       result = {}
 

data/lib/3scale/client/version.rb

@@ -1,5 +1,5 @@
 module ThreeScale
   class Client
-    VERSION = '2.3.3'
+    VERSION = '2.3.4'
   end
 end

data/test/client_test.rb

@@ -55,6 +55,12 @@ class ThreeScale::ClientTest < Test::Unit::TestCase
     @client.authrep(:app_id => "appid", :app_key => "appkey")
   end
 
+  def test_authrep_supports_service_id
+    assert_authrep_url_with_params "&%5Busage%5D%5Bhits%5D=1&service_id=serviceid"
+
+    @client.authrep(:service_id => "serviceid")
+  end
+
   #TODO these authrep tests
   def test_authrep_supports_api_key_auth_mode; end
   def test_authrep_log_is_encoded;end
@@ -115,6 +121,18 @@ class ThreeScale::ClientTest < Test::Unit::TestCase
     assert response.success?
   end
 
+  def test_successful_authorize_with_user_key
+    body = '<status>
+              <authorized>true</authorized>
+              <plan>Ultimate</plan>
+            </status>'
+
+    FakeWeb.register_uri(:get, "http://#{@host}/transactions/authorize.xml?provider_key=1234abcd&user_key=foo", :status => ['200', 'OK'], :body => body)
+
+    response = @client.authorize(:user_key => 'foo')
+    assert response.success?
+  end
+
   def test_authorize_with_exceeded_usage_limits
     body = '<status>
               <authorized>false</authorized>

metadata

@@ -1,8 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: 3scale_client
 version: !ruby/object:Gem::Version
-  version: 2.3.3
-  prerelease: 
+  version: 2.3.4
 platform: ruby
 authors:
 - Michal Cichra
@@ -13,12 +12,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-10-08 00:00:00.000000000 Z
+date: 2014-01-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -26,7 +24,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -34,81 +31,71 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rdoc
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: fakeweb
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: mocha
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 description: This gem allows to easily connect an application that provides a Web
@@ -125,7 +112,7 @@ files:
 - 3scale_client.gemspec
 - Gemfile
 - LICENCE
-- README.rdoc
+- README.md
 - Rakefile
 - VERSION
 - lib/3scale/authorize_response.rb
@@ -138,33 +125,26 @@ files:
 homepage: http://www.3scale.net
 licenses:
 - MIT
+metadata: {}
 post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -4299208069213055852
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
-      segments:
-      - 0
-      hash: -4299208069213055852
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.25
+rubygems_version: 2.1.11
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Client for 3scale Web Service Management System API
 test_files:
 - test/client_test.rb

data/README.rdoc

@@ -1,163 +0,0 @@
-= Rubygem for 3scale Web Service Management API
-
-{<img src="https://secure.travis-ci.org/3scale/3scale_ws_api_for_ruby.png?branch=master" alt="Build Status" />}[http://travis-ci.org/3scale/3scale_ws_api_for_ruby]
-
-3scale is an API Infrastructure service which handles API Keys, Rate Limiting, Analytics, Billing Payments and Developer Management. Includes a configurable API dashboard and developer portal CMS. More product stuff at http://www.3scale.net/, support information at http://support.3scale.net/.
-
-== Installation
-
-This library is distributed as a gem:
-
-  gem install 3scale_client
-
-Or alternatively, download the source code from github:
-http://github.com/3scale/3scale_ws_api_for_ruby
-
-If you are using Bundler, please add this to your Gemfile:
-
-  gem '3scale_client'
-
-and do a bundle install.
-
-If you are using Rails' config.gems, put this into your config/environment.rb
-
-  config.gem '3scale_client'
-
-Otherwise, require the gem in whatever way is natural to your framework of choice.
-
-== Usage
-
-First, create an instance of the client, giving it your provider API key:
-
-  client = ThreeScale::Client.new(:provider_key => "your provider key")
-
-Because the object is stateless, you can create just one and store it globally.
-
-==== Authrep
-
-Authrep is a 'one-shot' operation to authorize an application and report the associated transaction at the same time.
-The main difference between this call and the regular authorize call is that usage will be reported if the authorization is successful. Read more about authrep at the [active docs page on the 3scale's support site](https://support.3scale.net/reference/activedocs#operation/66)
-
-You can make request to this backend operation like this:
-
-  response = client.authrep(:app_id => "the app id", :app_key => "the app key")
-
-Then call the +success?+ method on the returned object to see if the authorization was
-successful.
-
-  if response.success?
-    # All fine, the usage will be reported automatically. Proceeed.
-  else
-    # Something's wrong with this application.
-  end
-
-The example is using the app_id authentication pattern, but you can also use other patterns.
-
-=== Using Varnish to speed up things
-
-3scale provides a [varnish module](https://github.com/3scale/libvmod-3scale) to cache the responses of its backend to help you achieve a close to zero latency. Go and install the module and [configure it the easy way](https://github.com/3scale/libvmod-3scale/blob/master/vcl/default_3scale_simple.vcl)
-
-When that's done all you have to do is to initialize your 3scale client pointing to the location of your varnish, by passing the host parameter to it, like this:
-
-  client = ThreeScale::Client.new(:provider_key => "your provider key", :host => "your.varnish.net:8080")
-
-that's it, your API should now be authorized and reported for you, and all that at full speed.
-
-=== Authorize
-
-To authorize an application, call the +authorize+ method passing it the application's id and
-optionally a key:
-
-  response = client.authorize(:app_id => "the app id", :app_key => "the app key")
-
-Then call the +success?+ method on the returned object to see if the authorization was
-successful.
-
-  if response.success?
-    # All fine, proceeed.
-  else
-    # Something's wrong with this application.
-  end
-
-If both provider key and app id are valid, the response object contains additional
-information about the status of the application:
-
-  # Returns the name of the plan the application is signed up to.
-  response.plan
-
-If the plan has defined usage limits, the response contains details about the usage broken
-down by the metrics and usage limit periods.
-
-  # The usage_reports array contains one element per each usage limit defined on the plan.
-  usage_report = response.usage_reports[0]
-
-  # The metric
-  usage_report.metric # "hits"
-
-  # The period the limit applies to
-  usage_report.period        # :day
-  usage_report.period_start  # "Wed Apr 28 00:00:00 +0200 2010"
-  usage_report.period_end    # "Wed Apr 28 23:59:59 +0200 2010"
-
-  # The current value the application already consumed in the period
-  usage_report.current_value # 8032
-
-  # The maximal value allowed by the limit in the period
-  usage_report.max_value     # 10000
-
-  # If the limit is exceeded, this will be true, otherwise false:
-  usage_report.exceeded?     # false
-
-If the authorization failed, the +error_code+ returns system error code and +error_message+
-human readable error description:
-
-  response.error_code    # "usage_limits_exceeded"
-  response.error_message # "Usage limits are exceeded"
-
-=== OAuth Authorize
-
-To authorize an application with OAuth, call the +oauth_authorize+ method passing it the application's id.
-
-  response = client.oauth_authorize(:app_id => "the app id")
-
-If the authorization is successful, the response will contain the +app_key+ and +redirect_url+ defined for this application:
-
-  response.app_key
-  response.redirect_url
-
-=== Report
-
-To report usage, use the +report+ method. You can report multiple transaction at the same time:
-
-  response = client.report({:app_id => "first app id",  :usage => {'hits' => 1}},
-                           {:app_id => "second app id", :usage => {'hits' => 1}})
-
-The :app_id and :usage parameters are required. Additionaly, you can specify a timestamp
-of transaction:
-
-  response = client.report({:app_id => "app id", :usage => {'hits' => 1},
-                            :timestamp => Time.local(2010, 4, 28, 12, 36)})
-
-The timestamp can be either a Time object (from ruby's standard library) or something that
-"quacks" like it (for example, the ActiveSupport::TimeWithZone from Rails) or a string. The
-string has to be in a format parseable by the Time.parse method. For example:
-
-  "2010-04-28 12:38:33 +0200"
-
-If the timestamp is not in UTC, you have to specify a time offset. That's the "+0200"
-(two hours ahead of the Universal Coordinate Time) in the example abowe.
-
-Then call the +success?+ method on the returned response object to see if the report was
-successful.
-
-  if response.success?
-    # All OK.
-  else
-    # There was an error.
-  end
-
-In case of error, the +error_code+ returns system error code and +error_message+
-human readable error description:
-
-  response.error_code    # "provider_key_invalid"
-  response.error_message # "provider key \"foo\" is invalid"