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 Swagger
to 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
The client application obtains an
access token
Each
access token
permits the client to consume the Heimdall API for one hour
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.
Install openssl
Generate a RSA private key to sign the certificate
openssl genrsa -out certificatePrivateKey.pem 2048
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
Create a certificate request and fill in the requested details (leave the challenge password blank)
openssl req -new -key certificatePrivateKey.pem -out certificateSigningRequest.csr
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
To find the certificate thumbprint, open
certificate.crt
and go toDetails
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
When prompted, enter a secure password for the certificate
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)
0 Comments