3scale

Page last updated:

3scale is a service that lets you manage API keys, apply rate limits, monitor analytics, and control developer accounts. 3scale features include the following:

  • API Access Control and Security
    • Issue and revoke API keys
    • Control access by developer and by application
    • Track and alert API limit violations
  • API Service Contracts, Rate Limiting, and Traffic Policies
    • Create and manage service contracts
    • Bundle functionalities of your API contracts
    • Set custom rate limits per developer and per application
  • API Analytics and Reporting
    • Track API usage by transaction or other metrics
    • Create reports per account and per application
    • Report on API usage trends
  • Developer Portal CMS and Interactive Documentation
    • Full-featured CMS with version control
    • Company branding
    • Active Docs REST API explorer
    • Automated email sign-up and developer management
    • Developer on-boarding and sign-up workflows

3scale API plugins provide connectivity to the 3scale architecture. Supported client libraries exist for Java, .NET, Node.js, Ruby, Perl, PHP, and Python.

Managing Services

Follow the steps below to add 3scale to your org and bind it to a space by selecting 3scale from the Pivotal Web Services Marketplace.

  1. Log in to the PWS Console.
  2. Select Marketplace from the left navigation menu.
  3. Click the 3scale tile.
  4. Select a plan that meets your needs.
  5. Configure the instance name and the space, and select an application to bind 3scale to from the Bind to App dropdown menu.

To create and bind a service instance from the command line, see Managing Service Instances with the CLI.

Using 3scale with Your Application

After subscribing to the 3scale service, log in to your 3scale dashboard. Navigate to the Account area and record your API Key, also known as your provider key. 3scale uses the provider key to authenticate when communicating with your application.

3scale api key

Pivotal recommends that you set this key as an environment variable to use in your integration code. The deployment instructions below assume that you have set your provider key to an environment variable named THREESCALE_PROVIDER_KEY.

Deployment Overview

3scale works using plugin agents that you can deploy anywhere that you want to enforce API control. 3scale provides plugins in multiple application languages for deployment in the application stack.

Once installed, agents authorize transactions on the API for valid keys, enforce rate limits, and report traffic back to the management system. A wide range of plugin/agent configuration options exist to meet different architectural needs. Alternatively, you can call the 3scale traffic management APIs directly.

Below are instructions for deploying the Java, Node.js, and Ruby plugins. You can find information for other plugins in their GitHub repositories and in the 3scale support portal.

Ruby

Installation

  1. Add the 3scale gem to your Gemfile:

    gem '3scale_client'

  2. Update application dependencies with Bundler:

      $ bundle install
      

Note: If you are using Rails config.gems, you can insert config.gem '3scale_client' in your config/environment.rb file instead of modifying the Gemfile.

Usage

Create an instance of the client, referencing your provider key. Pivotal recommends that you assign your provider key to an environment variable.

Example: client = ThreeScale::Client.new(:provider_key => ENV['THREESCALE_PROVIDER_KEY'])

Use your 3scale client to authorize incoming calls to your API. This plugin supports the following calls to the 3scale backend:

  • authorize: Grants access to your API
  • report: Reports traffic on your API
  • authrep: Grants access to your API and reports the traffic on it

3scale supports three authentication modes:

  • App ID
  • User Key
  • OAuth

App ID and User Key support authrep. OAuth requires separate authorize and report calls.

The following example uses the authrep call in App ID authentication mode.

response = client.authrep(:app_id => "APP ID", :app_key => "APP KEY")
if response.success?
  # Success. Usage will be reported automatically
else
  # Failure.
end

For more information, see the complete reference for the Ruby plugin in GitHub.

Node.js

Installation

Use npm to install the 3scale Node.js library:

$ npm install 3scale

Usage

Create an instance of the client, referencing your provider key. Pivotal recommends that you assign your provider key to an environment variable.

Use your 3scale client to authorize incoming calls to your API. This plugin supports the following calls to the 3scale backend:

  • authorize: Grants access to your API
  • report: Reports traffic on your API
  • authrep: Grants access to your API and reports the traffic on it

3scale supports three authentication modes:

  • App ID
  • User Key
  • OAuth

App ID and User Key support authrep. OAuth requires separate authorize and report calls.

The following example uses the authrep call in App ID authentication mode.

var Client = require('3scale').Client;

client = new Client(THREESCALE_PROVIDER_KEY);

client.authrep({"app_id": "your application id", "app_key": "your application key", "usage": { "hits": 1 } }, function(response){
  sys.log(sys.inspect(response));
});

For more information, see the complete reference for the Node.js plugin in GitHub.

Java

Installation

  1. Download the 3scale Java Maven project.
  2. Add a dependency to this artifact inside the application pom.xml file as follows:
    1. Within the downloaded 3scale artifact, open the pom.xml file.
    2. Retrieve the GroupID, ArtifactID, and Version from lines 5, 6, and 9 of this pom.xml file.
  3. Use the GroupID, ArtifactID, and Version to install the artifact to your repository as described in the Maven Guide to installing 3rd party JARs.

Usage

Create an instance of the client, referencing your provider key. Pivotal recommends that you assign your provider key to an environment variable.

Use your 3scale client to authorize incoming calls to your API. This plugin supports the following calls to the 3scale backend:

  • authorize: Grants access to your API
  • report: Reports traffic on your API
  • authrep: Grants access to your API and reports the traffic on it

3scale supports three authentication modes:

  • App ID
  • User Key
  • OAuth

App ID and User Key support authrep. OAuth requires separate authorize and report calls.

The following example uses the authrep call in App ID authentication mode.

package threescale.v3.api.example;

import threescale.v3.api.AuthorizeResponse;
import threescale.v3.api.ParameterMap;
import threescale.v3.api.ServerError;
import threescale.v3.api.ServiceApi;
import threescale.v3.api.impl.ServiceApiDriver;

/**
 * Simple Example of using the API
 */
public class Example {

    public void performAuthRep() {

        ServiceApi serviceApi = new ServiceApiDriver(THREESCALE_PROVIDER_KEY);    // Create the API object

        ParameterMap params = new ParameterMap();                           // Create top level ParameterMap
        params.add("app_id", "appid");                                      // Set the Users App Id

        ParameterMap usage = new ParameterMap();                            // Create 1st Level PM for usage
        usage.add("hits", "3");                                             // Add number of hits metric
        params.add("usage", usage);                                         // Add 1st level to top level as "usage"

        try {
            final AuthorizeResponse response = serviceApi.authrep(params);  // Perform the AuthRep and get the response

            if (response.success()) {                                       // Check if the AuthRep succeeded
                // Perform your calls there
            } else {
                // Handle failure here
            }
        } catch (ServerError serverError) {
            // Thrown if there is a communications error with the server.
            serverError.printStackTrace();
        }
    }
}

For more information, see the complete reference for the Java plugin in GitHub.

Dashboard

To access your 3scale dashboard, click Manage next to the 3scale service in Apps Manager.

For more information on the 3scale dashboard, see the 3scale support documentation.

Additional Documentation

Support

Report issues or provide product feedback to: support@3scale.net.

For more information, see Contacting Service Providers for Support.

Create a pull request or raise an issue on the source for this page in GitHub