Skip to content

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

License

Notifications You must be signed in to change notification settings

3scale-labs/3scale_ws_api_for_java

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

90 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Build Status

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

Plugin Versions

This is the version 3 of the plugin, if you were using this plugin before March 8th 2013, you are using the old version 2 of it, but we strongly recommend you to port your code to this new simpler version.

Synopsis

This plugin supports the 3 main calls to the 3scale backend:

  • authrep grants access to your API and reports the traffic on it in one call.
  • authorize grants access to your API.
  • report reports traffic on your API.

3scale supports 3 authentication modes: App Id, User Key and OAuth. The first two are similar on their calls to the backend, they support authrep. OAuth differs in its usage two calls are required: first authorize then report.

Install

This is a Maven project, to add it to your project you can use one of the following options:

  • add a dependency to this artifact inside your pom.xml like below (specify the version you need):

    <dependency>
        <groupId>net.3scale</groupId>
        <artifactId>3scale-api</artifactId>
        <version>3.0.4</version>
    </dependency>
    

    and run mvn install inside your project.

  • download the JAR file for the version you want to use and install it to your repository using the instructions described here: http://maven.apache.org/guides/mini/guide-3rd-party-jars-local.html

Usage on App Id auth mode

On App Id mode you call authrep to: grant access to your API, and also report the traffic on it at the same time.

// import the 3scale library into your code
import threescale.v3.api.*;
import threescale.v3.api.impl.*;

//  ... somewhere inside your code

// Create the API object with default settings. This will communicate with the 3scale platform SaaS default server.
ServiceApi serviceApi = ServiceApiDriver.createApi();

// When connecting to an on-premise instance of the 3scale platform, create the API object for a given host and port:
// ServiceApi serviceApi = ServiceApiDriver.createApi("backend.example.com", 80, true);


ParameterMap params = new ParameterMap();      // the parameters of your call
params.add("app_id", "your_app_id");           // Add app_id of your application for authorization
params.add("app_key", "your_app_key");         // Add app_key of your application for authorization

String serviceToken = ...;                     // Your 3scale service token
String serviceId = ...;                        // The service id of your application

ParameterMap usage = new ParameterMap(); // Add a metric to the call
usage.add("hits", "1");
params.add("usage", usage);              // metrics belong inside the usage parameter

AuthorizeResponse response = null;
// the 'preferred way' of calling the backend: authrep
try {
  response = serviceApi.authrep(serviceToken, serviceId, params);
  System.out.println("AuthRep on App Id Success: " + response.success());
  if (response.success() == true) {
    // your api access got authorized and the  traffic added to 3scale backend
    System.out.println("Plan: " + response.getPlan());
  } else {
    // your api access did not authorized, check why
    System.out.println("Error: " + response.getErrorCode());
    System.out.println("Reason: " + response.getReason());
  }
} catch (ServerError serverError) {
  serverError.printStackTrace();
}

Usage on API Key auth mode

On API Key mode you call authrep to: grant access to your API, and also report the traffic on it at the same time.

// import the 3scale library into your code
import threescale.v3.api.*;
import threescale.v3.api.impl.*;

//  ... somewhere inside your code

// Create the API object with default settings. This will communicate with the 3scale platform SaaS default server.
ServiceApi serviceApi = ServiceApiDriver.createApi();

// When connecting to an on-premise instance of the 3scale platform, create the API object for a given host and port:
//ServiceApi serviceApi = ServiceApiDriver.createApi("backend.example.com", 80, true);

ParameterMap params = new ParameterMap();              // the parameters of your call
params.add("user_key", "your_user_key");               // Add the user key of your application for authorization

String serviceToken = ...;                             // Your 3scale service token
String serviceId = ...;                                // The service id for your user key

ParameterMap usage = new ParameterMap(); // Add a metric to the call
usage.add("hits", "1");
params.add("usage", usage);              // metrics belong inside the usage parameter

AuthorizeResponse response = null;
// the 'preferred way' of calling the backend: authrep
try {
  response = serviceApi.authrep(serviceToken, serviceId, params);
  System.out.println("AuthRep on User Key Success: " + response.success());
  if (response.success() == true) {
    // your api access got authorized and the  traffic added to 3scale backend
    System.out.println("Plan: " + response.getPlan());
  } else {
    // your api access did not authorized, check why
    System.out.println("Error: " + response.getErrorCode());
    System.out.println("Reason: " + response.getReason());
  }
} catch (ServerError serverError) {
  serverError.printStackTrace();
}

Usage on OAuth auth mode

On OAuth you have to make two calls, first authorize to grant access to your API and then report the traffic on it.

// import the 3scale library into your code
import threescale.v3.api.*;
import threescale.v3.api.impl.*;

//  ... somewhere inside your code

// Create the API object with default settings. This will communicate with the 3scale platform SaaS default server.
ServiceApi serviceApi = ServiceApiDriver.createApi();

// When connecting to an on-premise instance of the 3scale platform, create the API object for a given host and port:
//ServiceApi serviceApi = ServiceApiDriver.createApi("backend.example.com", 80, true);

ParameterMap params = new ParameterMap();          // the parameters of your call
params.add("app_id",     "your_oauth_app_id");     // Add the app_id of your application for authorization

String serviceToken = ...;                         // Your 3scale service token
String serviceId = ...;                            // The service id of your application

ParameterMap usage = new ParameterMap(); // Add a metric to the call
usage.add("hits", "1");
params.add("usage", usage);              // metrics belong inside the usage parameter

// for OAuth only the '2 steps way' (authorize + report) is available
try {
    AuthorizeResponse response = serviceApi.oauth_authorize(serviceToken, serviceId, params);         // Perform OAuth authorize
    System.out.println("Authorize on OAuth Success: " + response.success());
    if (response.success() == true) {

      // your api access got authorized

      // you check the client's secret returned by the backend
      System.out.println("OAuth Client Secret: " + response.getClientSecret());

      // let's do a report
      ParameterMap transaction = new ParameterMap();
      transaction.add("app_id", "your_oauth_app_id");

      ParameterMap transaction_usage = new ParameterMap();
      transaction_usage.add("hits", "1");
      transaction.add("usage", transaction_usage);

      try {
          final ReportResponse report_response = serviceApi.report("your_oauth_service_id", transaction);

          if (report_response.success()) {
              System.out.println("Report on OAuth was successful");
          } else {
              System.out.println("Report on OAuth failed");
          }
      } catch (ServerError serverError) {
          serverError.printStackTrace();
      }
    } else {
      // your api access did not got authorized, check why
      System.out.println("Error: " + response.getErrorCode());
      System.out.println("Reason: " + response.getReason());
    }
} catch (ServerError serverError) {
    serverError.printStackTrace();
}

To test

To test the plugin with your real data:

  • edit the interface TestKeys and put in there your provider key as well as service ids and apps auth fields
  • run AllCallsExample class

About

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

Resources

License

Stars

Watchers

Forks

Packages

No packages published