Skip to main content

API v2 Documentation

Introduction​

Welcome to Energyworx APIv2, our next-generation API platform designed to empower user with seamless access to Energyworx services. Built on modern architectural principles, APIv2 offers an intuitive, efficient, and highly scalable interface for all your integration needs.

Key Benefits​

Domain-Driven Architecture​

Our API is thoughtfully organised into business domains, making it natural to find and integrate the exact services you need. This approach ensures that our API structure aligns perfectly with your business workflows.

Enterprise-Grade Design​

Built on industry-standard API design principles, APIv2 delivers:

  • Consistent patterns across all endpoints
  • Predictable behavior and responses
  • Comprehensive error handling
  • Robust security measures

Enhanced Developer Experience​

We've prioritised the developer journey with:

  • Detailed documentation for each service domain
  • Auto-generated client libraries
  • Interactive API examples
  • Comprehensive support resources

Service split​

Our API is split into multiple microservices each responsible for their own part of the Energyworx domain. At the moment the following services exist:

  • Identity, owns all Authentication & Authorization related resources.
  • Datasource, owns the data of the datasources and their classifiers.
  • Promo, owns Process Monitoring configuration.
  • Aggregation, owns timeseries aggregation configurations.
  • Flow, provides functionality to start flows and owns resulting metadata.

Getting Started​

  1. Authentication Setup Begin by accessing our Identity Service to obtain your API credentials.
  2. Core Services Integration Explore our domain-specific services based on your integration requirements.
  3. Documentation Resources Each service domain includes detailed documentation, example implementations, and best practices.
  4. Support Access Our dedicated support team is available to assist you throughout your integration journey.

Technical Standards​

APIv2 adheres to industry best practices, ensuring:

  • RESTful design principles
  • Consistent resource naming
  • Standard HTTP methods and status codes
  • Comprehensive error handling
  • Efficient pagination and filtering
  • Rate limiting and usage monitoring
  • Append-only design for audit compliance and versioned resources

Connecting to the API​

Authentication​

Outside of the JWTs signed by our identity provider, the identity service allows users to create client credentials for automated access. Access the API documentation on the NUI (New UI) to find out how to create and use client credentials.

Protocols​

Our API serve over gRPC but we run a gRPC-Gateway instance along side our API to serve over JSON. Both methods can be used for automated access, for simpler use cases without a high amount of throughput or calls we reccomend connecting to the JSON gateway as described in the API Documentation page on the NUI. For big workloads please reach out to our support team to set up a gRPC connection to your system. We will share an up to date gRPC stub for your specific programming language to be used to connect to the API, and give instructions on how to connect.