Swagger links

Links below are OpenAPI documentation for the services you will need to communicate through.

Egress service: https://waas-dev.azure-api.net/egress/swagger
Provisioning service: https://waas-dev.azure-api.net/provisioning/swagger
Ingest service: https://waas-dev.azure-api.net/ingest/swagger
Notification service: https://waas-dev.azure-api.net/notifications/swagger

Picture

Watts as a Service

This document serves as a draft for API documentation

Getting started

curl --location --request POST 'https://login.microsoftonline.com/c4101101-d8bc-426b-b3ea-4db330a69f92/oauth2/v2.0/token' \ 
--header 'Content-Type: application/x-www-form-urlencoded' \ 
--data-urlencode 'grant_type=client_credentials' \ 
--data-urlencode 'client_id=[ClientId]' \
--data-urlencode 'client_secret=[ClientSecret]' \
--data-urlencode 'scope=[Scope]'

Acquiring authentication token

We use Azure OAuth for authentication purposes.

Therefore, a JWT Bearer token will be needed in order to authenticate with all APIs.

Token is acquired through an HTTP endpoint (as in example)
(ClientId, ClientSecret and Scope will be provided by watts administrator upon request.)

var confidentialClient = ConfidentialClientApplicationBuilder
  .Create("[ClientId]")
  .WithClientSecret("[ClientSecret]")
  .WithAuthority("https://login.microsoftonline.com/c4101101-d8bc-426b-b3ea-4db330a69f92")
  .Build();
 
var accessTokenResponse = await confidentialClient.AcquireTokenForClient(
  new[] { "https://energybutlerb2c.onmicrosoft.com/dcb4ab73-bf15-49e0-ac12-d75601faa377/.default" })
  .ExecuteAsync();
 
var token = accessTokenResponse.AccessToken;

Alternatively, microsoft libraries (Microsoft.Identity.Client) could be used

var httpClient = new HttpClient(); 
defaultRequestHeaders.Authorization = 
  new AuthenticationHeaderValue("bearer", token);
 
await httpClient.GetAsync("https://waas-dev.azure-api.net/egress/<..>");

Calling an api

To call one of our endpoints, simply just add acquired token in the Authorization header as per OAuth JWT standard.

Data ingest pipeline

https://waas-dev.azure-api.net/provisioning/swagger

1. Provision a device

Send a request to provisioning service to persist device information and metadata required for forecasting.

2. Send consumptios

Send a request to Ingest API with batch of consumptions.

 https://waas-dev.azure-api.net/ingest/swagger

Keep in mind: Timeseries data must have a UTC timestamp

3. Get a notification callback

Subscribe to notification webhook to receive callback for ocurring events.

Some of most relevant events include:

  • ConsumptionsAvailable

  • ElectricityConsumptionForecastAvailable

  • ElectricityBaseLoadForecastAvailable

  • ElectricityBaseLoadEstimateAvailable

https://waas-dev.azure-api.net/notifications/swagger

4. Fetch data

When necessary event is received, data is available for fetching in Egress API.

 https://waas-dev.azure-api.net/egress/swagger