Implementation guide Partners in Energie notification and REST API

Notification API

First, there is the notification API, EDSN has an AMQP 1.0 broker that allows you to subscribe to events that happen on the Partners in Energie platform. This way your application can get automatically notified when something happens on the Partners in Energie platform.

REST API

Secondly, there is an REST based web API that allows you to synchronously interact with the Partners in Energie platform. For now, only a limited set of functionality is available, notifications are just being sent when a ticket or a comment gets created on the Partners in Energie platform, and the REST API only allows fetching information about these tickets and comments.

To connect with both API's your company first will have to be onboarded, to do this please reach out to our Servicedesk via [email protected].

Authentication

Authentication to both API's works with the OAuth protocol. To obtain an access token, the following steps must be performed:

• Create an OAuth Service account
• Create a client assertion
• Request an access token
  

Creating an OAuth Service Account

A service account can be created manually via the DVT UI.

Acceptance: https://portal.idp.acc.cmf.energysector.nl/gegevens

Production: https://portal.idp.cmf.energysector.nl/gegevens

Under the "Service Accounts" section, a service account can be created. Be sure to grant the service account the correct permissions and select the "OAuth" type. Make sure to store the private key of the service account securely, as it is needed to generate the client assertion.

Under “Applicatierollen” search for “AMQP” add the application role 'AMQP {env} consumer role to access pie for {organizationName}.'

Client Assertion

The client assertion is a JWT used to verify the client with the Identity Provider. It is a JWT signed with the private key of the service account. The client assertion must contain the following claims:

• iss (issuer): The client ID of the service account, which can be retrieved from the service account page.
• sub (subject): The client ID of the service account.
• aud (audience): The access token endpoint: https://idp.cmf.energysector.nl/am/oauth2/access_token
• exp (expiration): The expiration time of the client assertion. Note that this value pertains to the client assertion itself, not the access token. Five minutes is a good value.
• iat (issued at): The time at which the client assertion was issued.
• jti (JWT ID): A unique identifier for the client assertion, which can be generated using a UUID generator.

These claims must be signed with the private key of the service account obtained when the service account was created. This signed JWT is the client assertion.

Requesting an Access Token

To request an access token, a POST request must be sent to the access token endpoint. The access token endpoint is:

Acceptance: https://acc.idp.cmf.energysector.nl/am/oauth2/access_token

Production: https://idp.cmf.energysector.nl/am/oauth2/access_token

The request body must be a URL-encoded form containing the following parameters:

• grant_type: client_credentials
• client_id: The client ID of the service account, retrievable from the service account page.
• client_assertion_type: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
• scope: openid roles
• client_assertion: The client assertion (JWT) generated in the previous step.
  

Using the Access Token

The access token can be used to call an API. It must be included in the 'Authorization' header using the 'Bearer' scheme.

Notification API

This guide explains how to implement an AMQP consumer service in a programming language independent way. AMQP (Advanced Message Queuing Protocol) is an open standard application layer protocol for message-oriented middleware. It enables applications to send messages between systems regardless of platform or programming language.

At the moment, the message queue can contain two types of messages . The ticket created message and the comment created message. These messages remain in the queue for 1 day.

The ticket created message has the following format:

The comment created message has the following format:

Client library

Include the appropriate AMQP 1.0 client library for your programming language, for example:

• .NET: Amqp.Net.Lite
• Java: Apache Qpid
• Python: qpid-proton
• JavaScript: rhea
  

Configuration

Store and retrieve these settings:

• Broker URL/endpoint
  • Acceptance: amqps://:{BEARER_TOKEN}@amqp.acc.cmf.energysector.nl
  • Production: amqps://:{BEARER_TOKEN}@amqp.cmf.energysector.nl
• Queue name
  • /queues/energy-market.market-participant.partners-in-energy.notification.v1.{MARKETPARTY_EAN13}
• Authentication details (JWK, CLIENT_ID, TOKEN_URL)
  

Authentication

Implement a token service that:

• Acquires authentication tokens
• Refreshes tokens when needed, tokens are only valid for 1 hour.
• Securely stores credentials
  

Connection Management

• Create a connection to the AMQP broker
• Establish a session
• Create a receiver link attached to your queue
• Implement proper connection cleanup on shutdown
  

Message Processing

• Start a message consumer with a callback function
• Process received messages
  • To determine which message you consume from the queue you can look at the routing key.
    • The routing key is in the MessageAnnotations section of a consumed message.
    • It has the key "x-routing-key".
    • And a value in the following pattern: [ean13].[entity-type].[action] (e.g., "7627119388329.comments.created")
    • message.MessageAnnotations.Map["x-routing-key"]
• Acknowledge messages after processing
• Implement error handling
  

REST API

The Partners in Energie platform exposes three REST endpoints.

• GET {root-url}/pie-api/v1/tickets/{ticket-mrid}
• GET {root-url}/pie-api/v1/tickets/{ticket-mrid}/comments
• GET {root-url}/pie-api/v1/tickets/{ticket-mrid}/comments/{comment-mrid}

root-url acceptance: https://api.acc.cmf.energysector.nl

root-url production: https://api.cmf.energysector.nl

By consuming the messages from the notifications API the ticket and comment ids can be retrieved. With these ids it is possible to call these REST endpoints to retrieved detailed information about tickets and comments.

Similar to the notification API the REST API uses OAuth for for authentication, a token has to be retrieved and added in the 'Authorization' header prefixed with 'Bearer' when sending a request.