1. Oracle Utilities Opower REST APIOracle Utilities REST API for Digital Self Service Energy Management
  2. Testing the REST APIs
  3. Managing REST API Requests and Responses Using Postman

Managing REST API Requests and Responses Using Postman

Postman is a Chrome application that can send requests to a RESTFul web service. It can be used to test the APIs and capture HTTP requests and responses. 

Initial Postman Setup

Before you start managing requests, use your Google Chrome browser to download Postman from https://www.getpostman.com/apps.

Retrieving an Access Token and Authorizing APIs in Postman

Before you send requests using Postman, you must specify the necessary credentials to access the APIs, including an access token.

To retrieve an access token, you must first obtain credentials and create a Base64 encoded key. The steps to complete that process is described in Using OAuth 2.0 Authentication.

To retrieve an access token in Postman:

  1. Launch Postman.
  2. In the Request Builder, select POST as the request type.
  3. Include the URL to the token endpoint. Example:
    https://cxapi-stage.opower.com/apis/authorization-v1/oauth2/token
  4. Select the Headers tab. The header keys and values are displayed.
  5. Define the header as follows:

    • Key: Authorization

    • Value: Basic EncodedKey

      Where EncodedKey is the Base64 encoded key created when obtaining client credentials.
    • Description: Optional, can be left blank.
  6. Select the Body tab. The body options are displayed.
  7. Define the body as follows:

    • Content Type: x-www-form-urlencoded

    • Key: grant_type

    • Value: client_credentials

    • Description: Optional, can be left blank.
  8. Click Send. A response is displayed.

  9. Verify that the response is correct. The client_id value must match the client_id provided by Oracle Utilities Opower.

  10. Select the Headers, tab and then from the Presets drop-down list, select Manage Presets. The Manage Header Presets dialog box opens.

  11. Click Add.
  12. Provide a name and description for the new header preset, and then click Add.

  13. Click Save to save the request.

Refreshing an Access Token

If you have already retrieved an access token and saved the response as described in the process above, you can refresh the access token when it expires. Tokens expire after one hour.

To refresh an access token:

  1. Launch Postman.

  2. Open the saved request to create an access token.

  3. Click Send. A response is displayed.

  4. Select the Headers tab, and then from the Presets drop-down list, select Manage Presets. The Manage Header Presets dialog box opens.

  5. Select the preset header and update it with the refreshed access token, and then click Update.
  6. Click Save to save changes to the request.

Example: Retrieving a Customer Bill Comparison

This example provides detailed instructions on how to retrieve a customer bill comparison using Postman. This also serves as an example of using multiple requests. Resources are queried by their unique identifier. In many cases, you must combine multiple calls to retrieve the desired information when starting from information other than the identifier.

To retrieve a customer bill with Postman:

  1. Launch Postman.
  2. In the Request Builder, specify the URL of the resource that you want to access. In this example, the URL to access the resource is https://cxapi-stage.opower.com/apis/customer-data-v2/utilitycode/customers?8207421000 with the utility account number of 8207421000. Replace utilitycode with the applicable utility code.
  3. In the drop-down next to the request URL, select GET, and then click Send. The following response is returned:
    {
	response": {
		"name":"John Doe",
		"id":686380,
		"recipient":"RECIPIENT"
	}
}
    The response above includes the Oracle Utilities Opower customer ID of 686380, which you can use to retrieve the associated utility account IDs.
  4. In the Request Builder, specify the URL to access the resource as https://cxapi-stage.opower.com/apis/customer-data-v2/utilitycode/customers/686380/utility_accounts. Replace utilitycode with the applicable utility code.
  5. In the drop-down next to the request URL, select GET, and then click Send. The following response is returned:
    {
	response": [
		"id":807503,
		"meterType":"ELEC",
		"utilityAccountId":"8207482852",
		"moveInDate":"2008-04-04",
		"resolution":"BILLING",
		"utilityAccountId2":"8207482852"
	},
	{
		"id":1566055,
		"meterType":"GAS",
		"utilityAccountId":"8207482851",
		"moveInDate":"2008-04-04",
		"resolution":"BILLING",
		"utilityAccountId2":"8207482851"
	}]
}

    The response above includes the two associated utility account IDs of 807503 and 1566055. You can use the customer's gas account ID to retrieve the associated bill comparison.

  6. In the Request Builder, specify the URL to access the resource as https://cxapi-stage.opower.com/apis/billComparison-v2/utilitycode/bill-comparison/accounts/1566055. Replace utilitycode with the applicable utility code.
  7. In the drop-down next to the request URL, select GET, and then click Send. The following response is returned:
    {
	response": {
		"currencySymbol":"$",
		"reference": {
			"usage":18.0,
			"averageTemperature":57.551723,
			"startDate":"2011-04-01",
			"endDate":"2011-04-29",
			"charges":28.55
		},
		{
			"temperatureUnit":"FAHRENHEIT",
			"compared": {
				"usage":36.0,
				"averageTemperature":44.258064,
				"startDate":"2011-03-01",
				"endDate":"2011-03-31",
				"charges":43.83
		},
		"meterUnit":"THERM",
		"analysisResults": [
		{
			"analysisName":"WEATHER",
			"costDifferenceExplained":0.0
		},
		{
			"analysisName":"NUM_DAYS",
			"costDifferenceExplained":-2.8277419
		},
		{
			"analysisName":"OTHER",
			"costDifferenceExplained":-12.45
		}]
	{
}