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.9.0'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Client

Returns a new instance of Client.



50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/3scale/client.rb', line 50

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.



62
63
64
 
# File 'lib/3scale/client.rb', line 62

def host
  @host
end

#http ⇒ Object (readonly)

Returns the value of attribute http.



62
63
64
 
# File 'lib/3scale/client.rb', line 62

def http
  @http
end

#provider_key ⇒ Object (readonly)

Returns the value of attribute provider_key.



62
63
64
 
# File 'lib/3scale/client.rb', line 62

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)
usage::      predicted usage. It is optional. It is a hash where the keys are metrics
             and the values their predicted usage.
             Example: {'hits' => 1, 'my_metric' => 100}

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



212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/3scale/client.rb', line 212

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, AuthorizeResponse)
  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



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
99
 
# File 'lib/3scale/client.rb', line 67

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}
  path += "&#{usage_query_params(options_usage)}"

  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, AuthorizeResponse)
  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)
usage::      predicted usage. It is optional. It is a hash where the keys are metrics
             and the values their predicted usage.
             Example: {'hits' => 1, 'my_metric' => 100}

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



261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/3scale/client.rb', line 261

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, AuthorizeResponse)
  else
    raise ServerError.new(http_response)
  end
end

#report(*reports, transactions: [], service_id: nil, **rest) ⇒ Object

Report transaction(s).

Parameters

Hash with two fields:

transactions:: It is required. It is an enumerable. Each element is a hash with the fields:
      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
                 corresponding 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.
service_id::   ID of the service. It is optional. When not specified, the transactions
               are reported to the default service.

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. Using the default service.
client.report(transactions: [{:app_id => 'foo', :usage => {'hits' => 1}},
                             {:app_id => 'bar', :usage => {'hits' => 1}}])

Report one transaction with timestamp. Using the default service.
client.report(transactions: [{:app_id    => 'foo',
                              :timestamp => Time.local(2010, 4, 27, 15, 14),
                              :usage     => {'hits' => 1}])

Report a transaction specifying the service.
client.report(transactions: [{:app_id => 'foo', :usage => {'hits' => 1}}],
              service_id: 'a_service_id')

Note

The signature of this method is a bit complicated because we decided to keep backwards compatibility with a previous version of the method: def report(*transactions)



151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
 
# File 'lib/3scale/client.rb', line 151

def report(*reports, transactions: [], service_id: nil, **rest)
  if (!transactions || transactions.empty?) && rest.empty?
    raise ArgumentError, 'no transactions to report'
  end

  transactions = transactions.concat(reports)

  unless rest.empty?
    warn(DEPRECATION_MSG_OLD_REPORT)
    transactions.concat([rest])
  end

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

  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