= Interface for 3scale web service API monitoring system

This plugin provides interface for communication with 3scale monitoring system.

== Configuration

If you are using rails 2.1 or newer, put this into your config/environment.rb
file:

  config.gem "3scale_interface"

If you are using older version, put there this instead:

  require "3scale_interface"

== Usage

First, create new interface object with 3scale backed hostname and Your
private authentication key:

  interface = ThreeScale::Interface.new(backend_host, provider_key)

You can find the backend hostname on http://www.3scale.net/support/api.

Because the object is stateless, you can create just one and store it globally.

Then for each request to Your service:

1. Start the transaction with user key and (optionally) estimated resource
usage (in this example it is: 1 hit and 42000 kilobytes of storage space),

  transaction = interface.start(user_key, 'hits' => 1, 'storage' => 42000)

This will return transaction data (if successful). It is a hash containing
these fields:

<tt>:id</tt>::
  transaction id necessary for confirmation or cancellation of transaction
  (see following steps).

<tt>:provider_verification_key</tt>::
  the provider should send this key back to user so he/she can verify the
  authenticity of the response.

<tt>:contract_name</tt>::
  name of contract the user is signed for. This can be used to send
  different response according to contract type, if that is desired.

2. Process the request.

2a. If the processing was successful:
Call +confirm+:

  interface.confirm(transaction[:id])

Or call it with actual resource usage, if it differs from predicted one:

  interface.confirm(transaction[:id], 'hits' => 1, 'storage' => 40500)

2b. If there was some error, call +cancel+:

  interface.cancel(transaction[:id])

3. Send response back to the user together with +provider_verification_key+.

== Legal:

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