Class: ThreeScale::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/3scale/client.rb,
lib/3scale/client/version.rb,
lib/3scale/client/http_client.rb

Overview

Wrapper for 3scale Web Service Management API.

Example

client = ThreeScale::Client.new(:provider_key => "your provider key")

response = client.authorize(:app_id => "an app id", :app_key => "a secret key")

if response.success?
  response = client.report(:app_id => "some app id", :usage => {"hits" => 1})

  if response.success?
    # all fine.
  else
    # something's wrong.
  end
end

Defined Under Namespace

Classes: HTTPClient

Constant Summary collapse

DEFAULT_HOST = 
'su1.3scale.net'
VERSION = 
'2.6.1'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Client

Returns a new instance of Client.



44
45
46
47
48
49
50
51
52
53
54
 
# File 'lib/3scale/client.rb', line 44

def initialize(options)
  if options[:provider_key].nil? || options[:provider_key] =~ /^\s*$/
    raise ArgumentError, 'missing :provider_key'
  end

  @provider_key = options[:provider_key]

  @host = options[:host] ||= DEFAULT_HOST

  @http = ThreeScale::Client::HTTPClient.new(options)
end

Instance Attribute Details

#host ⇒ Object (readonly)

Returns the value of attribute host.



56
57
58
 
# File 'lib/3scale/client.rb', line 56

def host
  @host
end

#http ⇒ Object (readonly)

Returns the value of attribute http.



56
57
58
 
# File 'lib/3scale/client.rb', line 56

def http
  @http
end

#provider_key ⇒ Object (readonly)

Returns the value of attribute provider_key.



56
57
58
 
# File 'lib/3scale/client.rb', line 56

def provider_key
  @provider_key
end

Instance Method Details

#authorize(options) ⇒ Object

Authorize an application.

Parameters

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.
service_id:: id of the service (required if you have more than one service)

Return

An ThreeScale::AuthorizeResponse object. It’s success? method returns true if the authorization is successful, false otherwise. It contains additional information about the status of the usage. See the ThreeScale::AuthorizeResponse for more information. In case of error, the error_code returns code of the error and error_message human readable error description.

In case of unexpected internal server error, this method raises a ThreeScale::ServerError exception.

Examples

response = client.authorize(:app_id => '1234')

if response.success?
  # All good. Proceed...
end



187
188
189
190
191
192
193
194
195
196
197
198
199
200
 
# File 'lib/3scale/client.rb', line 187

def authorize(options)
  path = "/transactions/authorize.xml" + options_to_params(options, ALL_PARAMS)

  http_response = @http.get(path)

  case http_response
  when Net::HTTPSuccess,Net::HTTPConflict
    build_authorize_response(http_response.body)
  when Net::HTTPClientError
    build_error_response(http_response.body)
  else
    raise ServerError.new(http_response)
  end
end

#authrep(options) ⇒ Object

Authorize and report an application. TODO (in the mean time read authorize comments or head over to support.3scale.net/reference/activedocs#operation/66 for details



61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/3scale/client.rb', line 61

def authrep(options)
  path = "/transactions/authrep.xml?provider_key=#{CGI.escape(provider_key)}"

  options_usage = options.delete :usage
  options_log   = options.delete :log

  options.each_pair do |param, value|
    path += "&#{param}=#{CGI.escape(value.to_s)}"
  end

  options_usage ||= {:hits => 1}
  usage = []
  options_usage.each_pair do |metric, value|
    escaped_metric = CGI.escape "[usage][#{metric}]"
    usage << "#{escaped_metric}=#{CGI.escape(value.to_s)}"
  end
  path += "&#{usage.join('&')}"

  if options_log
    log = []
    options_log.each_pair do |key, value|
      escaped_key = CGI.escape "[log][#{key}]"
      log << "#{escaped_key}=#{CGI.escape(value)}"
    end
    path += "&#{log.join('&')}"
  end

  http_response = @http.get(path)

  case http_response
  when Net::HTTPSuccess,Net::HTTPConflict
    build_authorize_response(http_response.body)
  when Net::HTTPClientError
    build_error_response(http_response.body)
  else
    raise ServerError.new(http_response)
  end
end

#oauth_authorize(options) ⇒ Object

Authorize an application with OAuth.

Parameters

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

A ThreeScale::AuthorizeResponse object. It’s success? method returns true if the authorization is successful, false otherwise. It contains additional information about the status of the usage. See the ThreeScale::AuthorizeResponse for more information.

It also returns the app_key that corresponds to the given app_id

In case of error, the error_code returns code of the error and error_message human readable error description.

In case of unexpected internal server error, this method raises a ThreeScale::ServerError exception.

Examples

response = client.authorize(:app_id => '1234')

if response.success?
  # All good. Proceed...
end



233
234
235
236
237
238
239
240
241
242
243
244
245
246
 
# File 'lib/3scale/client.rb', line 233

def oauth_authorize(options)
  path = "/transactions/oauth_authorize.xml" + options_to_params(options, OAUTH_PARAMS)

  http_response = @http.get(path)

  case http_response
  when Net::HTTPSuccess,Net::HTTPConflict
    build_authorize_response(http_response.body)
  when Net::HTTPClientError
    build_error_response(http_response.body)
  else
    raise ServerError.new(http_response)
  end
end

#report(*transactions) ⇒ Object

Report transaction(s).

Parameters

The parameters the transactions to report. Each transaction is a hash with these elements:

app_id::    ID of the application to report the transaction for. This parameter is
            required.
usage::     Hash of usage values. The keys are metric names and values are
            correspoding numeric values. Example: {'hits' => 1, 'transfer' => 1024}.
            This parameter is required.
timestamp:: Timestamp of the transaction. This can be either a object of the
            ruby's Time class, or a string in the "YYYY-MM-DD HH:MM:SS" format
            (if the time is in the UTC), or a string in
            the "YYYY-MM-DD HH:MM:SS ZZZZZ" format, where the ZZZZZ is the time offset
            from the UTC. For example, "US Pacific Time" has offset -0800, "Tokyo"
            has offset +0900. This parameter is optional, and if not provided, equals
            to the current time.

Return

A Response object with method success? that returns true if the report was successful, or false if there was an error. See ThreeScale::Response class for more information.

In case of unexpected internal server error, this method raises a ThreeScale::ServerError exception.

Examples

# Report two transactions of two applications.
client.report({:app_id => 'foo', :usage => {'hits' => 1}},
              {:app_id => 'bar', :usage => {'hits' => 1}})

# Report one transaction with timestamp.
client.report({:app_id    => 'foo',
               :timestamp => Time.local(2010, 4, 27, 15, 14),
               :usage     => {'hits' => 1})

Raises:

  • (ArgumentError) 


139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
 
# File 'lib/3scale/client.rb', line 139

def report(*transactions)
  raise ArgumentError, 'no transactions to report' if transactions.empty?

  payload = encode_transactions(transactions)
  payload['provider_key'] = CGI.escape(provider_key)

  http_response = @http.post('/transactions.xml', payload)

  case http_response
  when Net::HTTPSuccess
    build_report_response
  when Net::HTTPClientError
    build_error_response(http_response.body)
  else
    raise ServerError.new(http_response)
  end
end