Client for 3scale Web Service Management API

3scale integration plugin for PHP applications. 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/.

Tutorials

• Plugin Setup: https://support.3scale.net/docs/deployment-options/plugin-setup
• Rate Limiting: https://support.3scale.net/docs/access-control/rate-limits
• Analytics Setup: https://support.3scale.net/quickstarts/3scale-api-analytics

Installation

Download the source code from github: http://github.com/3scale/3scale_ws_api_for_php and place it somewhere accessible from your project.

Usage

Require the ThreeScaleClient.php file (assuming you placed the library somewhere within the include path):

require_once('lib/ThreeScaleClient.php')

Then create an instance of the client

$client = new ThreeScaleClient();

NOTE: unless you specify ThreeScaleClient(); you will be expected to specify a provider_key parameter, which is deprecated in favor of Service Tokens:

$client = new ThreeScaleClient("your provider key");

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

Then you can perform calls in the client:

$response = $client->authorize("app id", "app key", new ThreeScaleClientCredentials("service id", "service token"));

$response = $client->report(array(array('app_id' => "app's id"],'usage' => array('hits' => 1))), new ThreeScaleClientCredentials("service id", "service token"));

NOTE:service_id is mandatory since November 2016, both when using service tokens and when using provider keys

Authorize

To authorize a particular application, call the authorize method passing it the application id and service id and optionally the application key:

$response = $client->authorize("app id", "app key", new ThreeScaleClientCredentials("service id", "service token"));

If you had configured a (deprecated) provider key, you would instead use:

$response = $client->authorize("the app id", "the app key", "service id"));

Then call the isSuccess() method on the returned object to see if the authorization was successful:

if ($response->isSuccess()) {
  // All fine, proceeed.
} else {
  // Something's wrong with this app.
}

If both provider 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->getPlan()

If the plan has defined usage limits, the response contains details about the usage broken down by the metrics and usage limit periods.

// The usageReports array contains one element per each usage limit defined on the plan.
$usageReports = $response->getUsageReports();
$usageReport  = $usageReports[0];

// The metric
$usageReport->getMetric() // "hits"

// The period the limit applies to
$usageReport->getPeriod()       // "day"
$usageReport->getPeriodStart()  // 1272405600 (Unix timestamp for April 28, 2010, 00:00:00)
$usageReport->getPeriodEnd()    // 1272492000 (Unix timestamp for April 29, 2010, 00:00:00)

// The current value the application already consumed in the period
$usageReport->getCurrentValue() // 8032

// The maximal value allowed by the limit in the period
$usageReport->getMaxValue()     // 10000

// If the limit is exceeded, this will be true, otherwise false:
$usageReport->isExceeded()      // false

If the authorization failed, the getErrorCode() returns system error code and getErrorMessage() human readable error description:

$response->getErrorCode()       // "usage_limits_exceeded"
$response->getErrorMessage()    // "Usage limits are exceeded"

Authrep

To authorize a particular application, call the authrep method passing it the application id and service id and optionally the application key:

$response = $client->authrep("app id", "app key", new ThreeScaleClientCredentials("service id", "service token"), array('hits' => 1));

Then call the isSuccess() method on the returned object to see if the authorization was successful:

if ($response->isSuccess()) {
  // All fine, proceeed.
} else {
  // Something's wrong with this app.
}

If both provider 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->getPlan()

You can also use other patterns such as user_key mode during the authrep call

$response = $client->authrep_with_user_key("user_key", new ThreeScaleClientCredentials("service id", "service token"), array('hits' => 1));

Report

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

$response = $client->report(array(
      array('app_id' => "first app's id",'usage' => array('hits' => 1)),
      array('app_id' => "second app's id", 'usage' => array('hits' => 1))), new ThreeScaleClientCredentials("service id", "service token"));

The "app_id", "usage" parameters are required alongiwth service id and service token. Additionaly, you can specify a timestamp of the transaction:

$response = $client->report(array(
  array('app_id'    => "app's id",
        'usage'     => array('hits' => 1),
        'timestamp' => mktime(12, 36, 0, 4, 28, 2010, new ThreeScaleClientCredentials("service id", "service token")));

The timestamp can be either an unix timestamp (as integer) or a string. The string has to be in a format parseable by the strtotime function. 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 above.

Then call the isSuccess() method on the returned response object to see if the report was successful:

if ($response->isSuccess()) {
  // All OK.
} else {
  // There was an error.
}

In case of error, the getErrorCode() returns system error code and getErrorMessage() human readable error description:

$response->getErrorCode()    // "provider_key_invalid"
$response->getErrorMessage() // "provider key \"foo\" is invalid"

Custom backend for the 3scale Service Management API

The default URI used for the 3scale Service Management API is http://su1.3scale.net:80. This value can be changed, which is useful when the plugin is used together with the on-premise version of the Red Hat 3scale API Management Platform.

In order to override the URL, pass the custom URI while creating instance an instance of the client

$client = new ThreeScaleClient(null, "http://custom-backend.example.com:8080");

Plugin integration

If you are interested in integrating the plugin with:

• Composer check the packagist. This is kindly maintained by daws.ca tech team.

• Symphony2 check tonivdv's 3scaleBundle. This is kindly maintained by Adlogix tech team.

To Test

To run tests: php test/all.php

Legal

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