= 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.

=== 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"