Vereniging-COIN.Sdk.WM

.NET WEAS Migration SDK

Introduction

This SDK supports secured access to the WEAS Migration API.

For a quick start, follow the steps below:

• Setup
• Configure Credentials
• Send Messages
• Consume Messages
• Error handling

Setup

Sample Project for the WEAS Migration API

A sample project is provided in the weas-migration-sdk-samples directory.

NuGet Package

This SDK is published as the NuGet package 'Vereniging-COIN.Sdk.WM'.

Configure Credentials

For secure access credentials are required.

• Check this README to find out how to configure these.
• In summary you will need:
  • a consumer name
  • a private key file (or a System.Security.Cryptography.RSA instance containing this key)
  • a file containing the encrypted Hmac secret (or a System.Security.Cryptography.HMACSHA256 instance containing this (decrypted) secret)
• These can be used to create instances of the WeasMigrationService and the SseConsumer, which is needed for the WeasMigrationMessageConsumer.

Messages

WmMessage.cs shows how the WEAS Migration domain has been structured. The interfaces from this file can be used to define methods that can accept any message. Coin.Sdk.WM.Messages.V5.Utils contains the useful static methods TypeName and Deserialize.

Send Messages

The WeasMigrationService has a SendMessage method to send any WEAS Migration message - wrapped in an instance of the MessageEnvelope class - to the API.

Consume Messages

Create Message Listener

For message consumption, the WEAS Migration API makes use of HTTP's ServerSentEvents. The SDK offers a Listener interface IWeasMigrationMessageListener which is triggered upon reception of a message payload. Whenever the API doesn't send any other message for 20 seconds, it sends an empty 'heartbeat' message, which triggers the OnKeepAlive() method.

Start consuming messages

The WeasMigrationMessageConsumer has three startConsuming...() methods for consuming messages, of which startConsumingUnconfirmed() is most useful. All these methods need an instance of the IWeasMigrationMessageListener.

Consume specific messages using filters

The WeasMigrationMessageConsumer provides various filters for message consumption. The filters are:

• MessageType: All possible message types, including errors. Use the MessageType-enumeration to indicate which messages have to be consumed.
• confirmation status: By using startConsumingAll(), all messages will be received, both confirmed and unconfirmed.
  Note: this enables the consumption of the whole message history. Therefore, this requires you to supply an implementation of the IOffsetPersister interface. The purpose of this interface is to track the message-id of the last received and processed message. In the case of a reconnect, message consumption will then resume where it left off.
• offset: starts consuming messages based on the given message-id offset. Note: it is the responsibility of the client to keep track of the offset.

Confirm Messages

Once a consumed message has been processed it needs to be confirmed. To confirm a message use the WeasMigrationService.sendConfirmation(id) method.

Error Handling

The WEAS Migration API can return errors in one of two ways:

1. The server received an incorrect payload and replies with an error response (synchronous)

   The REST layer of the system only performs basic payload checks, such as swagger schema validity and message authorization. Any errors in these checks are immediately returned as an error reply. The WeasMigrationService.SendMessage method returns these as ErrorResponse. Other http errors are thrown as HttpListenerException.

2. As a ServerSentEvent containing an WeasMigrationErrorFoundMessage (asynchronous)

   The system performs detailed functional validation asynchronously. Errors in this stage are sent via a ServerSentEvent.

   Note: WeasMigrationErrorFound messages need to be confirmed like any other message received via a ServerSentEvent.