Clean Energy API

This package provides Dart HTTP bindings for the Clean Energy backend APIs.

Features

• Easily create HTTP calls to Kohler Energy Management API endpoints
• Provides Dart classes that model the return values from the API
• Uses code generation based on swagger files, so code is always up-to-date using the backend as the source of truth

Usage

The APIs work like any Chopper service generated from swagger_dart_code_generator.

The original Clean Energy RDC2 API can be used like follows:

final CleanEnergyRdc2Api rdc2Api = CleanEnergyRdc2Api.create(
  baseUrl: Uri.parse(
    'https://az-amer-dev-hems-capp.icyrock-fcfd0b7a.eastus.azurecontainerapps.io/',
  ),
  interceptors: [apiKeyInterceptor],
);

final Response<List<GeneratorResponseModel>> generators = await rdc2Api
    .rdc2ApiV1GeneratorDealerEmailIdGet(dealerEmailId: 'dealer@example.com');

The V2 API, named the "Energy Management API", can be used like so:

final EnergyManagementApi energyManagementApi = EnergyManagementApi.create(
  baseUrl: Uri.parse(
    'https://az-amer-dev-hems-capp.icyrock-fcfd0b7a.eastus.azurecontainerapps.io/',
  ),
  interceptors: [oauthInterceptor],
);

final Response<List<DeviceV2>> devices =
    await energyManagementApi.kemproApiV2DevicesGet();

Similarly, the new V3 API, named the "Energy Management V3 API", can be used like so:

final EnergyManagementV3Api energyManagementV3Api =
    EnergyManagementV3Api.create(
  baseUrl: Uri.parse(
    'https://az-amer-dev-hems-capp.icyrock-fcfd0b7a.eastus.azurecontainerapps.io',
  ),
  interceptors: [oauthInterceptor],
);

final Response<List<DeviceDTO>> dealerDevices =
    await energyManagementV3Api.kemApiV3DealerDevicesGet();

Development

This packages uses code generation to create the Dart class bindings from the backend swagger files.

For development / debugging purposes, code generation can be done manually via the details below.

Manual code generation

Every time any swagger file in lib/src/raw_swaggers/ is updated, the following commands should be run:

dart run clean_energy_api:transform_swagger
dart run build_runner build

The first command generates transformed swagger files in lib/src/swaggers/, with some models changes to avoid name conflicts. The second command performs the actual generation of Dart service and model classes.

Generally, updates to the swagger files should also bump the package version.

Generated files should be checked in to source control, and they should be published as part of the package. This is done so that consumers can use the package directly.

Automatic code generation

Generally, the generation of Dart code is managed automatically via an Azure pipeline.

The pipeline is run every time the backend repo updates, and if changes to the swagger file are detected, the dart code generation will be run automatically and a pull request will be submitted to the project for review.

See swagger-codegen-pipeline.yml for specifics on how the automated code generation functions and can be tweaked.

Additional information

• Clean Energy Rdc2 API (v1) and Energy Management API (v2) source code
• Clean Energy API swagger Files