Public API v1.0 - Using the Public API

The following list contains the most common methods of using the ForeSee Public API:

Invoking OAuth Calls

To make Public API Calls, you must first obtain an OAuth2 Access Token using your Client Credentials. ForeSee supports the OAuth Client Credentials Flow only. Therefore, Public API Calls must be from server-side applications that can confirm the confidentiality of the credentials. The OAuth2 end point is served from a /token resource with grant_type and scope as two mandatory parameters. The grant_type query parameter has a value of client_credentials and whatever scope you need to access the eventual APIs. There scope currently for CX APIs namely r_cx_basic.
To make the token request, you must pass an Authorization header that is formed by Base64 encoding of consumer key: Basic + consumer secret pair (must be a space between “Basic” and the Consumer Secret Pair.

Example: Basic WEpLbmhrVEtQTnRLdlVNaEs1Vk5kM01XSTlWSTBRem46OEE2VFllN1JYczN0cE1KOW1EVzg=

Note: There is a space between “Basic” and “WEpLbmhrVEtQTnRLdlVNaEs1Vk5kM01XSTlWSTBRem46OEE2VFllN1JYczN0cE1KOW1EVzg=” above. In the above example, WEpLbmhrVEtQTnRLdlVNaEs1Vk5kM01XSTlWSTBRem46OEE2VFllN1JYczN0cE1KOW1EVzg= is obtained by concatenating the Consumer Key and Secret only separated by a colon, and then applying Base 64 encoding.
Please familiarize yourself with the OAuth Client Credentials Flow. The ForeSee server is a standard implementation of this flow.
If you are using the SDK, then you only need to do the following:

final AuthClient authClient = new AuthClient(Environment.DEVELOPMENT);
String accessToken = authClient.authenticateUsingClientCredentials(,,, false);

As you can see, the AuthClient needs the environment. Based on that, the Base URI changes since we have end points for DEV/QA/Staging and Production.

Invoking CX Measures API Calls

Once you have obtained an Access Token, you can make any of the Public API Calls by sending the required headers and respect the contract of the API. The Access Token itself goes in the Authorization header prefixed by the word Bearer.

Example: Bearer 54c76b50-472f-4010-a3be-f06811e16a04

In the above example, the value 54c76b50-472f-4010-a3be-f06811e16a04 is the Access Token.
If you are using the SDK, then you only need to do the following:

/** Initialize the CX Measures client */
final CxMeasuresClient cxMeasuresClient = new CxMeasuresClient(Environment.DEVELOPMENT, true);

MeasuresCollection measuresCollection = cxMeasuresClient.getMeasures(accessToken);
 
MeasureDefinition measureDefinition = cxMeasuresClient.getMeasurementDefinition(accessToken,, false,false);

This example is for getting the list of measures and measurement definition.

Example of invoking API calls in Java using HTTP Client

The following code snippet is an OAuth2 Token API Call which shows the mechanics of making a REST Call:

/** Build the Authorization header which is essentially a Base64 encoded value of consumer key: consumer secret pair */
String combinedCredentials = consumerKey + ":" + consumerSecret;
String base64EncodedHeader = BaseEncoding.base64().encode(combinedCredentials.getBytes());
String authHeader = AUTHORIZATION_HEADER_PREFIX_BASIC + base64EncodedHeader;
 
/** Build the Url - The Token URL is https://api.foresee.com/v1/token */
String baseUrl = buildTokenUrl();
String url = new StringBuilder(baseUrl).append("?grant_type=").
        append(GRANT_TYPE_CLIENT_CREDENTIALS).
        append("&scope=").
        append(scope).
        toString();
 
/** Add the headers needed to set the media type and Authorization */
Map<String, String> headers = new HashMap<String, String>();
headers.put(ACCEPT_HEADER, CONTENT_TYPE_JSON);
headers.put(CONTENT_TYPE_HEADER, CONTENT_TYPE_JSON);
headers.put(AUTHORIZATION_HEADER, authHeader);
 
/** Make the HTTP Request */
HttpClient client = new UrlHttpClient(new ClientConfiguration());
try {
    HttpRequest httpRequest = new HttpRequest("POST",
            new URI(url),
            headers, (InputStream)null);
    HttpResponse httpResponse = client.execute(httpRequest);
 
    /** If status code is 200 then your call was successful */
    if (httpResponse.getStatusCode() == 200) {
        /** Use a convenient JSON marshalling / unmarshalling library to marshal from Json to Java */
        Gson gson = new Gson();
        JsonReader reader = new JsonReader(new InputStreamReader(httpResponse.getContent()));
        reader.setLenient(true);
        OAuth2TokenResponse tokenResponse = gson.fromJson(reader,OAuth2TokenResponse.class);
        String accessToken = tokenResponse.getAccessToken();
        return accessToken;
    } else {
        throw ApiAuthenticationException.builder().
                message("Encountered an exception performing authentication").build();
    }
 
} catch (URISyntaxException e) {

Invoking API calls with Foresee Java SDK

ForeSee offers a Java SDK for making API Calls using a strongly typed interface. SDKs are grouped by category of API, each product having a separate SDK. When using Maven or Gradle, you can find the Java SDK on Maven Central by searching for the following artifact:

    com.foresee.platform
    public-api-sdk
    1.0.0-M5

Please note that the version tags may contain the latest version.

Search Query in Maven Central

http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.foresee.platform%22%20AND%20a%3A%22public-api-sdk%22
The following artifacts are stored on Maven Central:

  • The actual SDK JAR file
  • Javadocs for the SDK
  • Sources for the SDK
  • Assmebly that has the artifact library, as well as the dependent libraries, javadocs, and sources

If you do not use a dependency section, such as Maven or Gradle, then you must download a ZIP assembly which is also uploaded on Maven Central that has our SDK and all the dependencies. See below on how to search in Maven Central. In the example below, the 1.0.0-M6.zip is the assembly.


The downloaded ZIP file has the following structure:

  • SDK JAR
  • SDK Sources JAR
  • SDK Javadocs JAR
  • public-api-sdk/LICENSE.txt for the SDK license
  • public-api-sdk/NOTICE.txt for information about the licensing for dependent libraries
  • public-api-sdk/README.md has a read me file about usage
  • public-api-sdk/libs directory that has all the dependent libraries
  • public-api-sdk/libs-sources directory that has the sources for all the dependent libraries

Javadocs can be exported in order to generate an HTML version of the Java documentation for the SDK.

Other articles in this section:

  1. Using the Public API (current article)
  2. Oauth2 Client Credentials Flow