Plugin Setup

By the time you complete this tutorial, you'll have configured your API to use the available 3scale code plugins to manage access traffic.

There are several different ways to add 3scale API Management to your API – including using APIcast (API gateway), Amazon API Gateway with Lambda, 3scale Service Management API, or code plugins. This tutorial drills down into how to use the code plugin method to get you set up.

How plugins work

3scale API plugins are available for a variety of implementation languages including Java, Ruby, PHP, .NET, and others – the full list can be found in the code libraries section. The plugins provide a wrapper for the 3scale Service Management API to enable:

  • API access control and security
  • API traffic reporting
  • API monetization

This wrapper connects back into the 3scale system to set and manage policies, keys, rate limits, and other controls that you can put in place through the interface. Check out the Hello World API guide to see how to configure these elements.

Plugins are deployed within your API code to insert a traffic filter on all calls as shown in the figure.

Step 1: Select the your language and download the plugin

Once you've created your 3scale account (signup here), navigate to the code libraries section on this site and choose a plugin in the language you plan to work with. Click through to the code repository to get the bundle in the form that you need.

If your language is not supported or listed, let us know and we'll inform you of any ongoing support efforts for your language. Alternatively, you can connect directly to the 3scale Service Management API.

Step 2: Check the metrics you've set for your API

As described in the API definition tutorial, you can configure multiple metrics and methods for your API on the API control panel. Each metric and method has a system name that will be required when configuring your plugin. You can find the metrics in API > Definition area of your Admin Portal.

For more advanced information on metrics, methods, and rate limits see the specific tutorial on rate limits.

Step 3: Add the plugin code to your application

Armed with this information, return to the code and add the downloaded code bundle to your application. This step varies for each type of plugin, and the form that it takes depends on the way each language framework uses libraries. For the purposes of this tutorial, this example will proceed with PHP instructions. Other plugins integration details are included in the README documentation of each repository.

For PHP, require the ThreeScaleClient.php file (assuming you placed the library somewhere within the include path):


Then, create an instance of the client, giving it your provider API key:

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

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

Step 4: Add calls to authorize as API traffic arrives

To authorize a particular application, call the authorize method, passing it the application ID and (optionally) the application key:

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

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 the provider and the 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. 

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 a system error code and getErrorMessage() human readable error description:

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

Step 5: Report traffic usage

To report usage, use the report method. You can report multiple transactions 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))));

The "app_id" and "usage" parameters are required. 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))));

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 a system error code and getErrorMessage() human readable error description:

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

Note that as well as reporting traffic separately from authorizations, this can be done in a single call to the AuthRep method instead of report in the first instance.

Step 6: Deploy and run traffic

Once the required calls are added to your code, you can deploy (ideally to a staging/testing environment) and make API calls to your endpoints. As the traffic reaches the API, it will be filtered by the plugin and keys checked against issues API credentials. Refer to the Hello World API guide for how to generate valid keys – a set will have also been created as sample data in your 3scale account.

To see if traffic is flowing, log in to your API Admin Portal and navigate to the Analytics tab – there you will see traffic reported via the plugin.

Once the application is making calls to the API, they will become visible on the statistics dashboard and the Statistics > Usage page for more detailed view.

If you're receiving errors in the connection, you can also check the "Errors" menu item under Monitoring.