Configuring the Messaging REST API

With the introduction of the sedex Messaging REST API, new specific parameters are added to the sedex client configuration. This page explains these new configuration options.

Configuring the Messaging REST API consists primarily of:

• Enabling the Messaging REST API
• Specifying which interface to use for a given participant's incoming messages
• Defining users of the Messaging REST API for the business applications

Enabling/disabling the Messaging REST API

By default, the Messaging REST API is disabled for a new sedex client installation. It can optionally be enabled during the installation of the sedex client or can be enabled/disabled by adjusting the configuration later.

The Messaging REST API of an existing sedex client installation can be enabled / disabled by setting the parameter messaging.interface.rest-api.enabled in the central sedex Client configuration file sedex-client-configuration.properties. This configuration parameter is of type Boolean and possible values are true (enabled) or false (disabled).

Corresponding section in the configuration file:

  # If enabled, messages can be sent and received via sedex messaging
  # REST API. The OpenAPI spec is available at: # https://hostname:port/swagger-ui.html
  # Note: Messaging REST API is only available when wsproxy is started # (see wsproxy.start).
  messaging.interface.rest-api.enabled=true

Do not forget to restart

Changes to the central sedex client configuration file sedex-client-configuration.properties are only applied after a restart of the sedex client.

Messaging Interface Selector for incoming messages

Starting with version 7.0, the sedex client provides business applications with a "messaging REST API" via https in addition to the "classic file system interface" (inbox, outbox, receipts) for sending and receiving sedex messages.

As soon as the optional sedex Messaging REST API is enabled on the client, there are two different ways for business applications to receive incoming sedex messages. However, a sedex message addressed to a specific recipient can only be received via one or the other interface. Therefore, the Messaging Interface Selector built into the sedex client must decide for each incoming sedex message whether it should be delivered to the receiving business application via the classic File System Interface or the Messaging REST API.

Note

If a message is addressed to several recipients at a sedex client, it is decided for each of these recipients individually via which interface the message must be delivered. This can result in a message being delivered both in the file system and in one or more of the virtual inboxes in the REST API.

The configuration of the messaging interface selector for incoming messages basically consists of two parts:

1. Default Messaging Interface (mandatory)
   The default messaging interface defines to which messaging interface (files system or REST API) an incoming message should normally be delivered. As long as there is no specific rule for an incoming message, it will always be delivered in the default interface.

2. Specific rules (optional)
   In a newly introduced configuration file, specific rules can be used to define in a fine-grained way which messaging interface should be used to deliver an incoming sedex message to the business application. Specific rules allow defining the messaging interface based on two properties contained in the envelope (meta data) an incoming sedex message:

   • sedexID of a recipient (addressee)
   • messagType

Default messaging interface

Already during the installation, the default messaging interface for incoming messages must be defined if the messaging REST API is enabled. However, the default messaging interface can also be reconfigured later at any time.

The default messaging interface can be defined by setting the messaging.interface.selector.rule.default property in the conf/sedex-client-configuration.properties file. Possible values are: file-system or rest-api.

Corresponding section in the configuration file:

      # Defines, if the incoming messages should be delivered to the well known
      # file-system interface or the newly available rest-interface
      # Possible values of the parameter: "file-system" or "rest-api".
      # More specific rules for certain sedexIds or messageTypes can be
      # configured in "sedex-incoming-message-interface-rules.conf".
      messaging.interface.selector.rule.default=file-system

Specific rules

As long as all messages are delivered to the business application exclusively via file-system or exclusively via rest-api, specific rules are not necessary at all. Specific rules are only necessary if certain messages are to be received via the file system and certain messages via the REST API.

The conf/sedex-incoming-message-interface-rules.conf file can be used to specify general to very specific rules which determine the messaging interface to use to deliver an incoming sedex message to a business application. The configuration file contains a detailed explanation of specific rules and provides examples.

If two or more rules result in a conflict, the addressee-specific rule takes precedence over a message type-specific rule; a message type-specific rule will take precedence over the default messaging interface.

As soon as the specific rules configuration file of a running sedex Client is changed, the sedex Client will read and validate it automatically. Any lines containing errors will be marked and provided with an error message directly in the configuration file. Depending on the text editor used, it may be necessary to reload the configuration file or to open the configuration file again to see any errors.

File system encryption

Messages sent or received by the business application via the messaging REST API are automatically stored in encrypted form in the file system of the sedex client.

If required this local encryption can be switched off by setting the parameter messaging.encryption-in-client-filesystem.enabled in the central sedex Client configuration file sedex-client-configuration.properties to false. The configuration parameter is of type Boolean and possible values are true (enabled) or false (disabled).

Note

This file system encryption applies exclusively to the local intermediate storage of sedex message data sent or received via the REST API. Independently, all sedex messages are always encrypted end-to-end and thus transmitted securely over the network. End-to-end encryption cannot be switched off.

User management

Access to the Messaging REST API is secured by the Basic HTTP authentication scheme, therefore, each user (typically a business application) must be configured with a username and a password. The users are configured in the conf/sedex-wsproxy-user-configuration.properties file of the local sedex Client installation.

Normal users

Because the existing mechanism for configuring WS Proxy users is used to configure users of the Messaging REST API, the users are defined in the conf/sedex-wsproxy-user-configuration.properties file. See the separate documentation for more details on configuring normal WS-Proxy users.

A normal user configuration entry has the following format:

myUser1_name=aPassword,1-1234-1

Where

• admin_user_name is any name you choose for the administrator user.
• aPassword is the administrator's password which will be automatically and irreversibly encrypted by the sedex Client.
• 1-1234-1 is the sedex-ID assigned to the user.

Administrator user

A special administrator user can be defined. This user can carry out any REST operation for any other user.

The administrator user configuration entry has the following format:

admin_user_name=aPassword,administrator

Where

• admin_user_name is any name you choose for the administrator user.
• aPassword is the administrator's password which will be automatically and irreversibly encrypted by the sedex Client.
• administrator is the predefined role allowing the user to carry out any operation for any other configured user.

Danger

Administrator users must be used carefully only for administrative access where there is no other way. For security reasons, normal business applications should never access the messaging REST API with an administrator user. Instead, they should always use a normal user associated with their sedex ID.