Introduction

The Heimdall Cloud API offers an alternative way to digest power line data and works as a supplement to the Heimdall Cloud App for customers who are looking to process the data further to gain insights into the grid operation. The Heimdall Cloud API is built on the traditional REST architecture and offers the ability to periodically extract, process and analyze the grid data, through simple HTTP requests. Feel free to contact Heimdall if you have any questions or want to enable API access for your organization.

Documentation and testing with Swagger

The Heimdall Cloud API uses Swaggerto provide documentation for the different endpoints the API offers. Head over to the Swagger UI to see descriptions of each endpoint here.

The Swagger UI lets you experiment quickly with endpoint input and output. After you have been granted the API Consumer role, you can click the Authorize button and log in with the same account you use for the Heimdall Cloud App. This allows you to test endpoints with Swagger’s Try it out functionality.

Long-running jobs with a client application

For periodic data consumption a client application is required, which uses the OAuth 2.0 client credentials flow. In this flow a certificate(recommended) or a client secret is used to prove the client application’s identity. The flow works like this

1. The client application obtains an access token

   1. Each access token permits the client to consume the Heimdall API for one hour

2. The client calls the Heimdall API with the access token and renews the token when expired

The Heimdall API clients repository provides sample implementations in 3 languages. Each client implementation contains a README with instructions to get started.

• C# / .NET 5

• Java

• Python

API demo

Heimdall offers access to demo data if your organization wants to test out the capabilities of the Heimdall Cloud API. After you have been granted access, head out to Swagger demo version of the API here, or run your Heimdall API client of choice with the parameter useDeveloperApi set to false.

Certificate requirements

If your organization has a CA server(certificate authority server), it can be used to issue a signed X.509 certificate. Send the certificate to Heimdall to connect it to your client application.

If your organization does not have a CA server, you can create a self-signed certificate by following the instructions below.

1. Install openssl

2. Generate a RSA private key to sign the certificate

   openssl genrsa -out certificatePrivateKey.pem 2048

3. Create a PKCS8 version of the private key (only needed for the Java client)
   openssl pkcs8 -topk8 -inform PEM -outform DER -in certificatePrivateKey.pem -nocrypt > pkcs8PrivateKey.pem

4. Create a certificate request and fill in the requested details (leave the challenge password blank)

   openssl req -new -key certificatePrivateKey.pem -out certificateSigningRequest.csr

   

5. Create a .crt certificate (does not contain private key) with the private key and certificate signing request

   openssl x509 -req -days 36500 -in certificateSigningRequest.csr -signkey certificatePrivateKey.pem -out certificate.crt

   1. To find the certificate thumbprint, open certificate.crt and go to Details

      

6. Create a .pfx version of the certificate (contains the private key, but is secured with password)
   openssl pkcs12 -export -out certificate.pfx -inkey certificatePrivateKey.pem -in certificate.crt

   1. When prompted, enter a secure password for the certificate

7. Send the .crt certificate (does not contain private key) to Heimdall to connect it to your client application

The required certificate credentials required to authorize differ between the sample implementations in Java, Python and .NET.

Java

• Private key -pkcs8PrivateKey.pem

• Certificate - certificate.crt

Python

• Private key - privateKey.pem

• Certificate thumbprint (step 5a above)

.NET

• Certificate - certificate.pfx

• Certificate password to certificate.pfx (step 6a above)

• Certificate thumbprint (step 5a above)