= Client for 3scale web service management system API

This library provides client for the 3scale web service management API.

== Installation

This library is distributed as a gem. First, add gemcutter to your gem source list,
unless it's already there:

  gem source --add http://gemcutter.org

Then install the 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 Rails, 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.

=== Authorize

To authorize a particular user, call the +authorize+ method passing it the user key
identifiing the user:

  response = client.authorize(:user_key => "the user 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 user.
  end

If the authorization succeeded, the response object contains additional information about 
the status of the user:

  # Returns the name of the plan the user is signed up to.
  response.plan

If the plan has defined usage limits, the response contains details about how close the user
is to meet these limits:

  # The usages array contains one element per each usage limit defined on the plan.
  usage = response.usages[0]

  # The metric
  usage.metric # "hits"

  # The period the limit applies to
  usage.period       # :day
  usage.period_start # "Wed Apr 28 00:00:00 +0200 2010"
  usage.period_end   # "Wed Apr 28 23:59:59 +0200 2010"

  # The current value the user already consumed in the period
  usage.current_value # 8032

  # The maximal value allowed by the limit in the period
  usage.max_value     # 10000

If the authorization failed, the +errors+ method contains one or more errors with more
detailed information:

  error = response.errors[0]

  # Error code
  error.code    # "user.exceeded_limits"

  # Human readable error message
  error.message # "Usage limits are exceeded"

=== Report

To report usage, use the +report+ method. You can report multiple transaction at the same time:

  response = client.report({:user_key => "first user's key",  :usage => {'hits' => 1}},
                           {:user_key => "second user's key", :usage => {'hits' => 1}})

The :user_key and :usage parameters are required. Additionaly, you can specify a timestamp
of transaction:

  response = client.report({:user_key => "user's key", :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 were some errors
  end

If the report was successful, you are done. Otherwise, the +errors+ method will return array
of errors with more detailed information. Each of these errors has the +index+ attribute that
returns numeric index of the transaction this error corresponds to. For example, if you report
three transactions, first two are ok and the last one has invalid user key, there will be
an error in the +errors+ array with the +index+ equal to 2 (the indices start at 0):

  error = response.errors[0]
  error.index   # 2
  error.code    # "user.invalid_key"
  error.message # "User key is invalid"

== Legal

Copyright (c) 2010 3scale networks S.L., released under the MIT license.