Technical aspects
Introduction¶
Following are a selection of general topics relevant to calling operations provided by the Messaging REST API.
Endpoints/URLs¶
This section assumes that the sedex Client's Messaging REST API is enabled, is running on the local host, and is configured to use the default port number. If the sedex Client is running on a different host or using a different port, replace localhost and port number with the corresponding values.
Messaging REST API¶
The Messaging REST API can be accessed at this URL: localhost:8443/api/sedex/messaging/v1.
Reference documents the available operations.
SwaggerUI/OpenAPI specification¶
The built-in SwaggerUI provides a detailed documentation of the Messaging REST API operations and is a good starting point for interactively exploring and using the Messaging REST API. SwaggerUI provides the underlying OpenAPI Specification (JSON document), based on which a developer can use a tool to generate an API client for the programming language used to implement the business application.
The SwaggerUI of your sedex Client can be accessed at the following URL: localhost:8443/swagger-ui/index.html.
Errors¶
Operations that fail will return error information in the response. These are documented in your local SwaggerUI or in the API Reference documentation as Responses Schema.
Media types¶
The following media types are used by the Messaging REST API operations:
- application/hal+json
- application/json
- application/xml
For any given operation, your local SwaggerUI or the API Reference documentation Response body lists the valid media type(s).
Pagination¶
Pagination allows the calling business application to control how many and which results are returned. Several operations provide pagination by accepting optional page size and page number parameters. Page size specifies the maximum number of entries that will be returned per call. If the total number of available result entries exceed the page size, the caller can specify which page of the results should be returned.
Where available, the pagination parameters and their default values are documented in in your local SwaggerUI or in the API Reference documentation under Parameters.
Special case: Each time /send/receipts is called, it will return the 200 oldest unacknowledged receipts. That way, the oldest will not be orphaned.
Rate limits¶
With the goal of ensuring the availability of the sedex system for everyone and preventing an overload of the service, the operations of the sedex Messaging REST API listed below are subject to a rate limiter. If an application calls such an operation too often, it receives an error response with the status code 429 "Too Many Requests". The error message contains a hint after how many seconds the operation is allowed again.
| Operation | Maximum number of requests per minute |
|---|---|
| get unacknowledged receipts | 10 calls per user, per minute |
| check the status of a sent message | 120 calls per user, per minute |
| check the status of a sent message | 5 calls per user, per messageId, per minute |
API versioning¶
A commonly used way to version a REST API is to include the major version number in the URI path. Incompatible changes in a later version of the REST API would be expressed with a new major version number, resulting in a new URI. This approach allows multiple different versions of an API to be offered simultaneously, enabling gradual migrations over time.
The sedex Messaging REST API follows this strategy.
Currently, there is only one major version of the API and no new major versions are planned.
Idempotent operations¶
The only operation that is always idempotent, unless the configuration of a sedex participant is changed on the sedex Server, is send/messages/pre-check.
The following operations are idempotent until the specified message is deleted:
receive/message/{unique-sedex-message-id}/envelopereceive/message/{unique-sedex-message-id}/payload