SDKs

Three languages are supported:

NOTE: Version 8.*.* of the SDK is a major update. If you are currently using Version 7.*.* and upgrade there may be breaking changes.

The SDK going forward will follow the naming convention major version.YYMM of highest API version.build number.
For example SDK 8.2101.3196 means major version 8, V202101 is the latest API, 3196 is the build number.

Your base URI will depend on the environment your datasource is hosted in. Two common options are:

  • https://app.energycap.com (Production)
  • https://implement.energycap.com (Implementation)

These URLs are provided in the EnergyCap.Sdk.Extensions.EnergyCapEnvironments class.

Below are examples of what a simple call to get a list of Organizations/Buildings will look like in the available languages:

C# SDK

EnergyCapApiClientFactory

The C# SDK includes a factory class to assist with setting up a SDK client with the proper authorization as well as applying the correct JSON seralization settings to the underlying HttpClient used to send requests to EnergyCAP.

It is called EnergyCapApiClientFactory, and exists in the EnergyCap.Sdk.Extensions namespace.

EnergyCapApiClientFactory supports two types of authorization: API Keys, and Credential-based auth (although the latter will soon be deprecated; prefer API Key auth).

The following settings are available when creating an SDK instance through the ClientFactory:

  • EnvironmentUrl: The EnergyCAP environment to connect to.
    • While this can be set when using API Key authorization, it is not recommended if you are a hosted customer.
  • TimeoutSeconds: The number of seconds to wait before a request to EnergyCAP times out.
  • UserAgentSuffix: A suffix to apply to the user agent header of all outgoing requests.
  • HttpClientHandler: Adds the provided http client handler to the underlying HttpClient.
  • DelegatingHandlers: Adds delegating handlers to the underlying HttpClient.

Pagination in the C# SDK

Special consideration needs to be taken when calling paginated APIs with the C# SDK. Please see the paging tutorial for more information.

C# Example - API Key

using EnergyCap.Sdk; // Base namespace for the SDK
using EnergyCap.Sdk.Models; // Contains all of the request body and response objects
using EnergyCap.Sdk.Extensions; // This is the namespace of EnergyCapApiClientFactory and EnergyCapEnvironments

using System;
using System.Collections.Generic;
using System.Threading.Tasks;

namespace Sample
{
    internal class EnergyCapApiExample
    {
        internal async Task<(IList<PlaceResponse> places, GetPlacesHeaders pagingData)> GetPlaces(int pageSize, int pageNumber)
        {
            var settings = new EnergyCapClientSettingsApiKeyAuth
            {
                ApiKey = "your_api_key",
                TimeoutSeconds = 300,
            };

            var client = await EnergyCapApiClientFactory.CreateClientAsync(settings);

            // Get all places, paginated. See Pagination note above for more information
            var places = await client.GetPlacesWithHttpMessagesAsync(filter: "", pageSize: pageSize, pageNumber: pageNumber);

            return (places.Body, places.Headers);
        }
    }
}

C# Example - Credential

using EnergyCap.Sdk; // Base namespace for the SDK
using EnergyCap.Sdk.Models; // Contains all of the request body and response objects
using EnergyCap.Sdk.Extensions; // This is the namespace of EnergyCapApiClientFactory and EnergyCapEnvironments

using System;
using System.Threading.Tasks;
using System.Collections.Generic;

namespace Sample
{
    internal class EnergyCapApiExample
    {
        internal async Task<(IList<PlaceResponse> places, GetPlacesHeaders pagingData)> GetPlaces(int pageSize, int pageNumber)
        {
            // ====================================================
            // NOTE: Credential authentication will be deprecated. 
            // Please use API key authentication instead.
            // ====================================================
            var settings = new EnergyCapClientSettingsCredentialAuth
            {
                DataSource = "datasource",
                Username = "username",
                Password = "password",
                EnvironmentUrl = EnergyCapEnvironments.Implementation, //implement.energycap.com
                TimeoutSeconds = 300
            };

            var client = await EnergyCapApiClientFactory.CreateClientAsync(settings);

            // Get all places, paginated. See Pagination note above for more information
            var places = await client.GetPlacesWithHttpMessagesAsync(filter: "", pageSize: pageSize, pageNumber: pageNumber);

            return (places.Body, places.Headers);
        }
    }
}

Python (Beta)

Python Example

from energycap.sdk import EnergyCapApi, models

# Create the EnergyCAP SDK API client and set the base url
api = EnergyCapApi(base_url="your_base_uri")

# Call the Login API to retrieve an authentication token
authRequest = models.LoginRequest("datasource", "password", "username")
authResponse = api.login(login_request=authRequest)

# Set the token globally on the EnergyCAP SDK API client so that all subsequent API calls are authenticated
api.config.headers["Authorization"] = "bearer " + authResponse.token

places = api.get_places()

Angular/TypeScript (Beta)

Typescript Example

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { EnergyCapSdkModule, Configuration, BASE_PATH, PlaceService, 
  PlaceResponse, LoginRequest, LoginResponse, 
  AuthenticationService } from '@energycap/energycap-sdk-angular';
import { AppComponent } from './app.component';

const Config = new Configuration({
  apiKeys: {
    'Authorization': 'Bearer Token'
  }
});

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    EnergyCapSdkModule.forConfig(() => { return Config; })
  ],
  providers: [{
    provide: BASE_PATH,
    useValue: "your_base_uri"
  }],
  bootstrap: [AppComponent]
})
export class AppModule {
 
  constructor(
    protected authService: AuthenticationService,
    protected placeService: PlaceService
  ) {
    this.getPlaces();
  }

  private async getPlaces(): Promise<void> {
    let authRequest: LoginRequest = new LoginRequest();
    authRequest.dataSource = "datasource";
    authRequest.username = "username";
    authRequest.password = "password";

    // Call the Login API to retrieve an authentication token
    let authResponse: LoginResponse = await this.authService.login(authRequest).toPromise();

    // Set the token globally on the EnergyCAP SDK API client so that 
    // all subsequent API calls are authenticated
    Config.apiKeys["Authorization"] = "Bearer " + authResponse.token;

    let places: PlaceResponse[] = await this.placeService.getPlaces().toPromise();
  }
}