CC Tutorial5 - External Web Services

brainCloud provides an HTTP Client proxy object, retrieved via the bridge, that allows you to make HTTP GET requests to external 3rd party servers.

The HTTPClientProxyObject currently has a number of public methods. The methods are defined at the bottom of this page. The ‘serviceCode’ parameter in these methods refers to the value assigned in the portal configuration.

External Web Service Example

The following is an example script for requesting weather information from World Weather Online.

// GetWeather script - takes the following parameters
// location - location to get the weather for - example "Ottawa, Canada"
// API key from WorldWeatherOnline.com
var key = "ad1c12629a14edf04a8796042206a";
// Path to the api method
var path = "free/v2/weather.ashx";
// Retrieve the HTTP Client proxy
var httpClientService = bridge.getHttpClientServiceProxy();
// Construct the query parameters (they will be automatically encoded in the URL)
var queryMap = {
    "q": data.location,
    "num_of_days": 1,
    "format": "json",
    "key": key
};
// No need to send anything specific in the headers
var headers = {};
// Make the request
var result = httpClientService.getResponseJson("getweather", path, queryMap, headers);
// Log the results (debugging)
bridge.getLogServiceProxy().logInfo("Weather results", JSON.stringify(result));
// Return the results
var retval = null;
if (result.status === 200)
{
    retval = result.data.json.data;
}
retval;

In order to access 3rd party servers, it’s base URL must be configured in the portal under Design | Cloud Code | Web Services. This example needs a server named “getweather” with an URL of “https://api.worldweatheronline.com” added to list.

Try it yourself

Follow these steps to try this for yourself.

Step 1 – Create the Script

Via Design | Cloud Code | Edit Scripts in the portal.

Step 2 – Add the Service to the Whitelist

Via Design | Cloud Code | Web Services in the portal.

Step 3 – Test from the API Explorer

Go to API Explorer (Design | Cloud Code | API Explorer)
Authenticate the user – select the Authenticate service, then Authenticate Operation, and click the Go icon (Green Right Triangle). You may have to play with the authentication parameters a bit (to ensure you’re specifying a valid platform, etc.)
Call the Cloud Script – choose the Script service, then “Run Script GetWeather” for the operation. Customize the parameters if you’d like, and then hit Go.

Et voila!

Note – if you are going to use this service in your app, please go to WorldWeatherOnline and get your own API key!

getResponseJson

/**
 * Gets a JSON formatted document via HTTP.
 * @param serviceCode Web service service code
 * @param path Resource path.
 * @param query Optional query.
 * @param headers map of extra headers
 * @return Json object.
 *        
 * {
 *    status : 200,
 *    data : {
 *        statusCode : 200,
 *        json : {
 *            "key" : "value"
 *        }
 *    }
 * }
 */
public NativeObject getResponseJson(String serviceCode, String path, NativeObject query, NativeObject headers)

getResponseText

/**
 * Gets text document via HTTP.
 * @param serviceCode Web service service code
 * @param path Resource path.
 * @param query Optional query.
 * @param headers map of extra headers
 * @return Json object.
 * {
 *    status : 200,
 *    data : {
 *        statusCode : 200,
 *        text : "text string"
 *    }
 * }
 */
public NativeObject getResponseText(String serviceCode, String path, NativeObject query, NativeObject headers)

postFormResponseJson

/**
 * Posts a form encoded document via HTTP and expects a JSON response.
 * @param serviceCode Web service service code
 * @param path Resource path.
 * @param headers map of extra headers
 * @param form form parameters.
 * @return Json object.
 * {
 *    status : 200,
 *    data : {
 *        statusCode : 200,
 *        json : {
 *            "key" : "value"
 *        }
 *    }
 * }
 */
public NativeObject postFormResponseJson(String serviceCode, String path, NativeObject headers, NativeObject form)

postFormResponseText

/**
 * Posts a form encoded document via HTTP and expects a Text response.
 * @param serviceCode Web service service code
 * @param path Resource path.
 * @param headers map of extra headers
 * @param form form parameters.
 * @return Json object.
 * {
 *    status : 200,
 *    data : {
 *        statusCode : 200,
 *        text : "text string"
 *    }
 * }
 */
public NativeObject postFormResponseText(String serviceCode, String path, NativeObject headers, NativeObject form)

postJsonResponseJson

/**
 * Posts a JSON formatted document via HTTP and expects a JSON response.
 * @param serviceCode Web service service code
 * @param path Resource path.
 * @param headers map of extra headers
 * @param json JSON formatted data to post.
 * @return Json object.
 * {
 *    status : 200,
 *    data : {
 *        statusCode : 200,
 *        json : {
 *            "key" : "value"
 *        }
 *    }
 * }
 */
public NativeObject postJsonResponseJson(String serviceCode, String path, NativeObject headers, NativeObject json)

postTextResponseText

/**
 * Posts a text document via HTTP and expects a Text response.
 * @param serviceCode Web service service code
 * @param path Resource path.
 * @param headers map of extra headers
 * @param form form parameters.
 * @return Json object.
 * {
 *    status : 200,
 *    data : {
 *        statusCode : 200,
 *        text : "text string"
 *    }
 * }
 */
public NativeObject postTextResponseText(String serviceCode, String path, NativeObject headers, String text)

CC Tutorial5 – External Web Services