Introduction to the sedex Messaging REST API¶

The page lists some important points about the sedex Messaging REST API as an introduction.

Messaging REST API compatibility with classic file system interface¶

sedex Clients using the Messaging REST API are fully compatible with sedex Clients using the classic file-based messaging interface. Following the classic file-based messaging interface, the Messaging REST API also uses the concept of an envelope and a payload for a sedex message. The envelope contains the message's metadata (such as sender, recipient, etc.) and the payload file contains the business-specific data.

The sedex Messaging REST API is a feature provided by the sedex Web Service Proxy component of the locally installed sedex Client. The Web Service Proxy acts as a translator between the Messaging REST API and the file system. Because messaging still runs indirectly via sedex's classic file-based system, a given sedex Client can be configured to send or receive sedex messages with both interfaces, with the restriction that a specific message for a given participant must always use one or the other interface.

Overview: The sedex Messaging process¶

This diagram show the typical steps involved in sending and receiving sedex messages using the Messaging REST API.

sedex Client Messaging REST API

Sending a message¶

First a message is registered. A successful registration returns a unique-sedex-message-id (USMID) which identifies the message throughout the rest of the messaging process; a failed registration returns the reason for the failure. After a successful registration, the payload is uploaded. After the recipient receives the message, the sedex platform issues a receipt which the sender must acknowledge. The sender periodically checks for a list of unacknowledged receipts and acknowledges then to complete the process.

Tracking a message¶

Any time after a successful registration, the status of the message can (optionally) be checked using the USMID.

Receiving a message¶

The recipient periodically requests either a list of incoming message USMIDs or a list of incoming message envelopes. In the first case, the recipient can then make a second call to get the corresponding envelope. Based on the contents of an envelope and its business context, the recipient should determine whether it will process the message or not. The recipient will then download the payload and use its contents for its business purposes and delete the message in order to keep the disk space usage to a minimum.

Authentication¶

All calls to the Messaging REST API require the Basic HTTP authentication scheme. The user's names and passwords (which the sedex Client will encrypt) are defined in a configuration file. User management explains how to do this.

Temporary message files are encrypted¶

Messages sent or received via the Messaging REST API are automatically stored in encrypted form in the file system of the sedex Client. This local encryption can be switched off via a specific configuration property if required.

Dispatching messages to different users (business applications) via virtual inboxes¶

Users can be defined for each business application. Using the Messaging REST API, business applications will access user-specific virtual inbox in the sedex Client. This eliminates the need for applications to dispatch messages to various logical sedex IDs, as was sometimes the case in the past.