Solace REST HTTP Message Encoding

The Solace REST messaging feature encodes messages using standard HTTP mechanisms. Solace REST messages contain the following parts:

A POST request-target where the Solace PubSub+ event broker destination is encoded (refer to HTTP Request-Target)
HTTP headers that identify message properties of the REST message (refer to Solace REST Usage of HTTP Headers)
Message payloads that are transported as the HTTP message contents (refer to Message Encoding Considerations)

HTTP Request-Target

The Solace event broker REST HTTP interface supports HTTP request-targets in RFC 7230 §5.3.2 origin-form (that is, a path starting with a /) or in RFC 7230 §5.3.2 absolute-form (that is, <scheme>://<authority>/<path>)

When the Solace event broker acts as an HTTP server, it receives REST HTTP requests from message producers. The Solace event broker converts the received HTTP request-target into a Solace messaging topic, on which it routes the message.

Conversely, when the Solace event broker acts as an HTTP client, in a REST delivery point (RDP), it constructs the HTTP request-target from an outgoing Solace message before sending the HTTP request to the message consumer.

This conversion between HTTP request-target and Solace message depends on whether the corresponding Message VPN is configured for REST HTTP messaging mode or Microgateway mode.

Messaging Mode

REST HTTP Client to Solace Event Broker HTTP Server

When the Solace event broker receives an HTTP POST request from a REST HTTP producer client, the HTTP POST request-target's path must be one of the following:

/QUEUE/queue-name

The Solace event broker enqueues the message from the HTTP POST request into the message-spool queue named queue-name.
/TOPIC/topic-string

The Solace event broker publishes the message from the HTTP POST request to the topic topic-string.

If both /TOPIC and /QUEUE are omitted from the start of the request-target path, then /TOPIC is assumed and the incoming message is treated as if it came to /TOPIC/<topic-string>.

Solace Event Broker RDP to a REST HTTP Consumer Server

When the Solace event broker RDP sends an HTTP POST request to a REST HTTP consumer server, it uses the request-target that is configured for the corresponding queue binding. For more information, refer to Configuring POST Request Targets.

Microgateway Mode

REST HTTP Client to Solace Event Broker HTTP Server

When the Solace event broker receives an HTTP request from a REST HTTP producer client, the Solace event broker publishes the Solace message using the topic:

method/path

Where:

method is the HTTP request's method (one of DELETE, GET, HEAD, OPTIONS, PATCH, POST, or PUT)

path is the path from the HTTP request-target, with any leading / characters stripped.

A query, if any, in the HTTP request-target does not form part of the topic the Solace event broker uses to publish the message.

The Solace event broker restrictions on the length and characters in the resultant message topic must be respected.

An HTTP request-target may use percent-encoding to represent characters which are meaningful to the application, but which are illegal or otherwise-meaningful in an HTTP request-target (see RFC 3986 §2).

If a REST HTTP client sends the Solace event broker a request with any of the following characters percent-encoded in the request-target's path, they will appear to remain percent-encoded in the Solace topic:

! $ % & ' ( ) * + , / : ; = ? @ [ ]

Any other percent-encoded characters in the HTTP request-target from the REST HTTP client will be decoded in the Solace message topic.

Solace Event Broker RDP to REST HTTP Consumer Server

When the Solace event broker RDP sends an HTTP request to a REST HTTP consumer server, it uses the metadata from the message to construct the HTTP request-target. If the Solace event broker originally received the message from a REST HTTP producer client, then this metadata should serve to reconstruct that original request-target.

If the message does not have any metadata describing the request-target for the outgoing HTTP request, the Solace event broker reconstructs the request-target path from the message's topic. The top-level topic must be a supported HTTP method (one of DELETE, GET, HEAD, OPTIONS, PATCH, POST, or PUT). If not, the outgoing message will be discarded as unformattable. The second and successive subsequent topic levels form the request-target's path.

When the HTTP request-target path is reconstructed from the Solace topic, the following characters in the Solace topic will not be percent-encoded in the request-target:

! $ & ' ( ) * + , - . / 0…9 : ; = ? @ A…Z [ ] _ a…z ~

If the RDP queue binding from which the message was dequeued is not provisioned to replace-target authority (see Replacing the Authority Value in Outbound URIs), and the message contains metadata indicating the request-target's authority host, then the outgoing HTTP request-target will be in absolute-form. The scheme will be https or http, depending on whether the connection to the REST HTTP consumer server uses TLS transport. The authority (host and optionally port) will be those from the message's metadata.

Otherwise, the outgoing HTTP request-target will be in origin-form, without any scheme or authority.

In all cases, if the message contains metadata containing a request-target query, that query will be appended to the outgoing HTTP request-target.

Solace REST Usage of HTTP Headers

Solace REST messaging makes use of standard HTTP headers and introduces some custom headers specifically related to the Solace REST implementation. The following sections detail the HTTP headers used and provide context around their usage.

In messaging mode, any HTTP header fields not specifically mentioned below are ignored and discarded.
In Microgateway mode, any received HTTP header fields not specifically mentioned below will be attached to the Solace message as metadata. Any Solace message sent as an HTTP message will have the Solace message metadata converted back into HTTP header fields.

Where maximum field lengths are noted, the event broker enforces those maximums and discards any messages that violate them. Where applicable, an appropriate HTTP error is returned to the HTTP publisher to indicate the failure.

Standard HTTP Headers on HTTP Requests to Solace

A Solace PubSub+ event broker uses the following HTTP standard header fields on HTTP requests from REST HTTP clients:

Header Key/Value	Description
Authorization: Basic base64(username: password)	Refer to Configuring Client Authentication for details related to client authentication.
Authorization: Bearer	Refer to OAuth Authentication for details related to OAuth client authentication.
Connection: close	See RFC 7230 §6.1.
Content-Encoding	In both messaging and Microgateway modes, the received `Content-Encoding` is always attached as metadata to the Solace message.
Content-Length: digits	See RFC 7230 §3.3.2.
Content-Type: string	This field indicates whether the event broker should treat the REST message contents as Text or Binary when encoding the entity-body from a REST publisher into a Solace message. HTTP Content Entity Headers and Message Payload Types outlines how the values of this entity header are mapped to Solace message types. Note that text message content must be UTF-8 encoded. For more information refer to Message Encoding Considerations. In both messaging and Microgateway modes, any received `Content-Type` is always attached as metadata to the Solace message.
Forwarded: string X-Forwarded-For: string	As described in RFC 7239, if there are intermediate agents (for example, proxies or switches) between the originating HTTP client and the event broker, the IP addresses of the originating HTTP client up to the penultimate intermediate agent are listed in the `X-Forwarded-For` header. A Solace PubSub+ event broker makes use of this information in its Access Control Lists (ACLs), CLI and management screens to display appropriate extra details relating to the originating client’s IP. In Microgateway mode, if the event broker receives an HTTP request with `Forwarded` or `X-Forwarded-For` header(s), and the event broker RDP subsequently sends that message as an HTTP request, the event broker will append another `Forwarded: for=` header field containing the IP address of the directly-connected HTTP client which sent the HTTP request to the event broker.
Max-Forwards: integer	In messaging mode, the event broker ignores this header. In Microgateway mode, if the event broker receives an HTTP request with a `Max-Forwards` header, and the `Max-Forwards` value is less than or equal to zero, the HTTP request is discarded with a `400 Max-Forwards Exceeded` error. If the `Max-Forwards` value isn't exceeded, and the event broker subsequently sends that message as an HTTP request, the HTTP request also has a `Max-Forwards` header with its value decremented by one.
Transfer-Encoding: chunked	A Solace PubSub+ event broker supports HTTP POST requests sent using chunked transfer encoding as outlined in RFC 7230. A Solace event broker ignores and discards any trailing headers.
User-Agent: string	This header is displayed when you issue a `show client details` CLI command on the event broker.

Standard HTTP Headers on HTTP Responses from Solace

A Solace PubSub+ event broker always provides the following HTTP standard header fields in HTTP responses to REST HTTP clients:

Header Key/Value	Description
Cache-Control: no-cache	In messaging mode, the Solace event broker always sends a `Cache-Control: no-cache` header field. In Microgateway mode, any `Cache-Control` header field is passed transparently through the Solace event broker as Solace message metadata.
Content-Encoding	In both messaging and Microgateway modes, the Solace event broker sends any `Content-Encoding` metadata attached to the Solace response message.
Content-Length: digits	See RFC 7230 §3.3.2.
Content-Type: string	In both messaging and Microgateway modes, the Solace event broker sends any `Content-Type` metadata attached to the Solace response message. In messaging mode, if no `Content-Type` metadata is attached to the Solace response message, a Solace PubSub+ event broker sets this header based on the message type of the Solace message. For more information, refer to HTTP Content Entity Headers and Message Payload Types. For text messages the value is `text/plain` or `text/xml`. For all other messages the value is `application/octet-stream` to indicate binary.
Server: Solace_<platform>/<version>	In messaging mode, the `platform` component indicates the Solace platform type (for example, 3560). The `version` is the Solace PubSub+ version that the event broker is running (for example, 7.x.x.x). In Microgateway mode, any Server header field is passed transparently passed through the Solace event broker as Solace message metadata.
Set-Cookie: string	In messaging mode, a string that uniquely identifies the HTTP publisher client. This enables intermediate equipment, such as HTTP proxies or load balancers, to optimize future by keeping all traffic from a single REST publisher on the same HTTP connection. In Microgateway mode, any `Set-Cookie` headers fields are passed transparently passed through the Solace event broker as Solace message metadata.
Warning: 299 - “string”	Optional, as per RFC 7234. If present, indicates that the event broker has transformed a Solace message into an HTTP response, but some aspects of the Solace message could not be represented in the HTTP response and were omitted. More information may be conveyed in the `Solace-Warning` HTTP header.

Standard HTTP Headers on HTTP Requests from Solace

On HTTP requests from a Solace PubSub+ event broker to a RDP consumer HTTP server, the event broker provides the following standard HTTP header fields:

Header Key/Value	Description
Authorization: Basic base64(configured_ authentication_string)	If the event broker is configured to use basic authentication when establishing outgoing connections to RDP consumer HTTP servers, the event broker provides the `Authorization` header on each HTTP request. If basic authentication is not configured for outgoing connections to RDP consumer HTTP servers, the event broker does not provide the `Authorization` header field.
Cache-Control: no-cache	In messaging mode, the Solace event broker always sends a `Cache-Control: no-cache` header field. In Microgateway mode, any `Cache-Control` header field is passed transparently through the Solace event broker as Solace message metadata.
Content-Length: digits	See RFC 7230 §3.3.2.
Content-Type: string	In both messaging and Microgateway modes, the Solace event broker sends any `Content-Type` metadata attached to the Solace message. In messaging mode, if no `Content-Type` metadata is attached to the Solace message, a Solace PubSub+ event broker sets this header based on the message type of the event broker message. For more information, refer to HTTP Content Entity Headers and Message Payload Types. For text messages the value is `text/plain` or `text/xml`. For all other messages the value is `application/octet-stream` to indicate binary.
Host: <host>:<port>	See RFC 7230 §5.4.
User-Agent: Solace_<platform>/<version>	In Microgateway mode, any `User-Agent` header field is passed transparently passed through the Solace event broker as Solace message metadata. In messaging mode, the `platform` component indicates the Solace platform type (for example, 3560). The `version` is the Solace PubSub+ version that the event broker is running (for example, 7.1.x.x).
Warning: 299 - “string”	Optional, as per RFC 7234. If present, this warning indicates that the event broker has transformed a Solace message into an HTTP request, but some aspects of the Solace message could not be represented in the HTTP request and were omitted. More information may be conveyed in the `Solace-Warning` HTTP header.

Standard HTTP Headers on HTTP Responses from RDP Consumer HTTP Servers to Solace

A Solace PubSub+ event broker interprets the following standard HTTP header fields on HTTP responses from RDP consumer HTTP servers:

Header Key/Value	Description
Connection: close	Any value of the Connection header other than `close` is ignored.
Content-Encoding	In both messaging and Microgateway modes, the Solace event broker sends any `Content-Encoding` metadata attached to the Solace message.
Content-Length: digits	See RFC 7230 §3.3.2.
Content-Type: string	This field indicates whether the event broker should treat the HTTP response message contents as text or binary when encoding the entity-body into a Solace message. HTTP Content Entity Headers and Message Payload Types outlines how the values of this entity header are mapped to Solace message types. In both messaging and Microgateway modes, the Solace event broker also attaches any `Content-Type` to the Solace message metadata.
Transfer-Encoding: chunked	The event broker supports HTTP responses sent using chunked transfer encoding as outlined in RFC 7230. The event broker ignores and discards any trailing headers.

Solace-Specific HTTP Headers

All Solace-Specific HTTP headers are prefixed with Solace. Applications should not use Solace as a prefix for application specific headers to avoid confusion.

In both messaging and Microgateway modes, the Solace-specific HTTP headers described below are not attached transparently to the Solace message's metadata. Instead, the Solace event broker takes some local action described below when it receives HTTP messages with these headers, Conversely, the Solace event broker may attach these headers when it transmits HTTP messages, reflecting some local processing it performed on the message.

Header Key/Value	Description
Solace-Client-Name: Solace String (See Header Value Encoding - Solace String)	Specifies the event broker client name for the HTTP requests from an HTTP client. Client names must be unique within the Solace Message VPN for the HTTP connection. If this parameter is not provided, the event broker automatically generates a unique Solace event broker client name. To set the event broker client name, it is only necessary to provide this header once over the lifetime of an HTTP connection. It is acceptable to provide it on every HTTP request if the value remains constant. If an HTTP client sends a new value for `Solace-Client-Name`, then the event broker creates a new client session with this new client name. You must ensure that this name is unique within the Message VPN, otherwise the event broker follows the global authentication setting for replacing duplicate client connections. The maximum length for a `Solace-Client-Name` is 160 bytes. `Solace-Client-Name` is not used for HTTP requests sent from the Solace event broker to an RDP consumer HTTP server.
Solace-Client-Description: Solace String (See Header Value Encoding - Solace String)	Specifies the event broker client description for the HTTP requests from an HTTP client. A Solace PubSub+ event broker client description field is displayed in Solace event broker admin screens; it provides extra details about the client. To set the Solace event broker client description, it is only necessary to initially provide this header once over the lifetime of an HTTP connection. However, it is acceptable to provide it for every HTTP request if the value remains constant. If an HTTP client sends a new value for `Solace-Client-Description`, then the Solace event broker client session is updated with this new description. The maximum length for a `Solace-Client-Description` is 254 bytes.
Solace-Time-To-Live-In-ms: <milli-seconds>	Specifies a time-to-live value for the Solace guaranteed messages created from the received HTTP message. If this header is not present, messages do not have a time-to-live.
Solace-DMQ-Eligible: [true\|false]	Specifies whether Solace guaranteed messages created from the received HTTP message are flagged as eligible for a Dead Message Queues (DMQ). If this header is not present, messages are not eligible for the dead message queue.
Solace-Correlation-ID: Solace String (See Header Value Encoding - Solace String)	Specifies a Solace message correlation ID string. See Message Correlation for more information on message correlation. The maximum length for `Solace-Correlation-ID` is 2023 bytes.
Solace-Delivery-Mode: [Direct \| Non-Persistent \| Persistent]	Specifies the Solace delivery mode for the received HTTP request. If absent on a received HTTP request, the Solace event broker defaults to a delivery mode of persistent in messaging mode, or direct in Microgateway mode.
Solace-Message-ID: Solace String	Specifies a Solace message ID string. See Message Correlation for more information. The maximum length for `Solace-Message-ID` is 2023 bytes.
Solace-Reply-To-Destination: /(QUEUE \|TOPIC)/ <destination_string>	Specifies a reply-to destination for the received HTTP request. The event broker encodes this destination in the Solace message so that Solace messaging APIs (including the JMS implementation) recognize the destination as the reply-to. When using the `Solace-Reply-To-Destination`, the format of this field must follow the convention outlined in REST HTTP Client to Solace Event Broker HTTP Server. However, the destination type string , `/QUEUE/` for durable queues and `/TOPIC/` otherwise, is mandatory in this case. When `Solace-Reply-To-Destination` is used, applications can send requests and later receive asynchronous replies to those requests. Applications involved in the message exchange are responsible for correlating the request and async reply. The `Solace-Reply-To-Destination` header field is useable only in messaging mode. The `Solace-Reply-To-Destination` header field is mutually exclusive with the `Solace-Reply-Wait-Time-In-ms` header field. The maximum length for `destination_string` is 250 bytes.
Solace-Reply-Wait-Time-In-ms: <milli-seconds>	Specifies that the received HTTP request from the HTTP client is the request of a request-reply message exchange pattern, and that the Solace event broker must wait up to the specified timeout value for an application reply which the Solace event broker encodes into the HTTP response to the HTTP client. In Microgateway mode, all received HTTP requests are inherently requests of a request-reply message exchange pattern, and the `Solace-Reply-Wait-Time-In-ms` serves to change the timeout from the default of 30 seconds. In messaging mode, the presence of the `Solace-Reply-Wait-Time-In-ms` serves as a flag to indicate that the HTTP request is the request of a request-reply message exchange pattern; if `Solace-Reply-Wait-Time-In-ms` is not present in messaging mode, the Solace event broker sends an HTTP response containing no application-level reply payload to the HTTP client. In addition to integer values, the `Solace-Reply-Wait-Time-In-ms` header may have a value of `FOREVER`, which means the Solace event broker is to wait forever for an application reply. The HTTP connection must be closed to unblock in a failure scenario. When the Solace event broker sends an HTTP request to an RDP consumer HTTP server, the Solace event broker sets a `Solace-Reply-Wait-Time-In-ms` header value of `FOREVER` for those HTTP requests that are requests of a request-reply message exchange pattern. The `Solace-Reply-To-Destination` header field is mutually exclusive with the `Solace-Reply-Wait-Time-In-ms` header field.
Solace-Timestamp: <milliseconds since 1970-01-01 00:00 UTC>	Specifies the time at which the message was originally generated, as a 64-bit decimal integer giving the time in milliseconds since January 1, 1970 00:00 UTC. If absent, no time stamps are set for Solace messages. If present, the event broker does not perform any verification or enforcement on the value of this time stamp.
Solace-User-Property-<name>: <value> [; type=<type>]	This header allows users to specify properties that are carried end-to-end through the event broker. These properties are encoded as user properties in the resulting Solace message. For details on how add custom headers to REST messages see Solace Message Custom Properties.
Solace-Warning: "string"	This string accompanies the standard `Warning` header, and provides additional information describing the cause of the warning. It is intended for troubleshooting purposes.

Message Correlation

In the request-reply message exchange pattern, the HTTP client sends the Solace event broker an HTTP request. The Solace event broker converts the HTTP request to a Solace request message, then routes that message to some service provider according to the HTTP message's request-target. The service provider generates and sends a reply message back to the Solace event broker. The Solace event broker converts the reply message to an HTTP response, and sends the HTTP response to the HTTP client. This request-reply message exchange pattern is used for all HTTP messages in Microgateway mode, and for HTTP requests with the Solace-Reply-Wait-Time-In-ms header in messaging mode.

Solace messages have a pair of metadata fields, message ID and correlation ID, which are used to associate reply messages with their associated requests in a request-reply message exchange. The Solace message's message ID is accessible through the SMF message header ApplicationMessageID and the JMS header JMSMessageID; the Solace message's correlation ID is accessible through the SMF message header ApplicationCorrelationID and the JMS header JMSCorrelationID.

An HTTP client sending an HTTP request to the Solace event broker can provide its own message ID and correlation ID using the Solace-Message-ID and Solace-Correlation-ID HTTP headers, respectively. If an HTTP client sends an HTTP request to the Solace event broker for a request-reply message exchange pattern, and the HTTP client does not provide a Solace-Message-ID header, the Solace event broker synthesizes a unique message ID for the request message. This synthesized message ID has the form ID:Solace-<unique_val>, where <unique_val> is a unique 64-bit integer expressed in hexadecimal. Similarly, if the HTTP client does not provide a Solace-Correlation-ID header, the Solace event broker synthesizes a unique correlation ID for the request message. If the Solace event broker synthesizes both the message ID and correlation ID, the same value is used for both. The Solace event broker attaches the message ID and correlation ID as metadata to the Solace request message. The Solace event broker also attaches reply-to metadata to the Solace message, allowing the replying service provider to route the reply message back to the HTTP client.

When the Solace event broker receives a possible reply message routed to the HTTP client, it verifies that the reply message's message ID or correlation ID match those of the request message. Specifically,

the reply's message ID must match the request's message ID, or
the reply's correlation ID must match the request's message ID, or
the reply's correlation ID must match the request's correlation ID.

If any of those matches occur, the Solace event broker sends the reply message as an HTTP response to the HTTP client. HTTP requires that there be exactly one HTTP response for each HTTP request, so each matching message ID or correlation ID can be used only in a single request-reply message exchange pattern. If the reply message does not have a matching message ID or correlation ID as above, or if the reply message's matching message ID or correlation ID has already been consumed by an earlier reply message, the reply message is discarded.

When a Solace event broker sends a Solace message as an HTTP request to an RDP consumer HTTP server, the Solace event broker sets the Solace-Message-ID and Solace-Correlation-ID HTTP headers to those of the Solace message's message ID and correlation ID metadata, respectively. When the Solace event broker receives the HTTP response from the RDP consumer HTTP server, it creates a Solace reply message corresponding to the HTTP response. The Solace event broker sets the message ID of the Solace reply message to one of the following, in order of decreasing preference:

the Solace-Message-ID of the received HTTP response;
the Solace-Message-ID of the sent HTTP request;
nothing

The Solace event broker sets the correlation ID of the Solace reply message to one of the following, in order of decreasing preference:

the Solace-Correlation-ID of the received HTTP response;
the Solace-Correlation-ID of the sent HTTP request;
the Solace-Message-ID of the sent HTTP request;
the Solace-Message-ID of the received HTTP response
nothing.

Note that the above allow an RDP consumer HTTP server to generate replies in request-reply message exchange patterns, without the RDP consumer HTTP server itself having to be aware of Solace-Message-ID and Solace-Correlation-ID headers. The Solace event broker will synthesize the message ID and correlation ID necessary to allow the RDP consumer HTTP server's HTTP responses to be used as reply messages.

When the Solace event broker sends the HTTP response to the HTTP client, any message ID and correlation ID metadata in the Solace message appears in the HTTP response's Solace-Message-ID and Solace-Correlation-ID headers.

HTTP Header Value Encoding

The following note relates to HTTP header value encoding.

Header Value Encoding - Solace String

When the HTTP headers expect a value of Solace String, this indicates a text string meeting the following conditions such that both ASCII visible characters and all other UTF-8 characters are supported.

SolacePubSub+ Event Broker Message Field Defaults for REST Messages

A Solace PubSub+ event broker converts messages received from an HTTP client to the internal Solace message format so that they can be routed to any clients connected to the event broker. In doing this, the event broker assigns default behaviors for the following Solace message fields that are not configurable through Solace REST messaging.

Solace Message Field Default Values

Solace Message Field	REST Default
Eliding Eligible	Messages received from a REST producer are not eligible for eliding. (The message eliding capabilities of Solace PubSub+ enable clients to receive only the most current Direct messages published to topics that they subscribe to.) This field has a value of false.
Message COS	Messages received from a REST producer have a value class of service (COS) value of 1. For Direct messages this is the lowest class of service; for persistent and non-persistent messages this means low priority. For persistent and non-persistent messages (that is, Guaranteed messages), if the destination queue or topic endpoint is enabled to reject low-priority messages when it is overly congested, the assigned COS value determines each message’s discard eligibility.
Deliver To One	Messages received from a REST producer are not flagged as deliver-to-one (DTO) (that is, this field has a value of false).
Sender ID	Messages received from a REST producer do not have a sender ID field set, and the field is not present in Solace messages.
JMS Message Priority	Messages received from a REST producer do not have a JMS message priority field set, and the field is not present in Solace messages.

Message Encoding Considerations

In general, the message content is encoded as UTF-8 text or binary bytes in the body of the POST. The following sections outline some aspects to consider.

HTTP Content Entity Headers and Message Payload Types

Solace PubSub+ supports the following message types:

binary – unstructured bytes
text – a structured message containing a string as message content
map – a structured message containing key value pairs of Solace structured data
stream – a structured message containing stream of Solace structured data types (that is, a sequence of data fields without keys)

The REST API supports both binary and text message types.

The encoding of the Map and Stream message types are not supported over REST messaging. If a particular message exchange pattern results in the event broker sending a Solace message of an unsupported type to a REST consumer, or sending a Solace response of an unsupported type back to a REST producer, the HTTP body is omitted from the HTTP message. Further, the HTTP message contains Warning and Solace-Warning headers indicating that HTTP body has been omitted and why.

By extension, JMS Map, Stream, and Object messages are not supported over REST messaging.

The following sections outline details of the HTTP Content-Type and Content-Encoding header and how these headers affect the resulting Solace message.

HTTP Content-Type Mapping to Solace Message Types

When a REST producer sends an HTTP request to the event broker, or a REST consumer sends an HTTP response to the event broker, the event broker uses the HTTP Content-Type, HTTP Charset and HTTP Content-Encoding to determine whether to create a Solace text or binary message.

The event broker creates a Solace message with a text attachment under the following conditions:

HTTP Content-Type One of: HTTP Charset One of: HTTP Content-Encoding One of:

HTTP Content-Type One of:		HTTP Charset One of:		HTTP Content-Encoding One of:
`text/` `application/json` `application/xml` `application/xml-dtd` `application/javascript` `application/ecmascript` `application/+json` `application/*+xml`	AND	`UTF-8` `US-ASCII` parameter is absent	AND	`identity` header is absent

text/*
application/json
application/xml
application/xml-dtd
application/javascript
application/ecmascript
application/*+json
application/*+xml

AND

UTF-8
US-ASCII
parameter is absent

AND

identity
header is absent

Otherwise, the event broker creates a Solace message with a binary attachment.

The HTTP Content-Type and HTTP Content-Encoding are also carried within the Solace message as a Solace API property so that end applications can make use of these header field values when processing the message. The following outlines the rules outlining how these headers are encoded in the Solace message:

The HTTP Content-Encoding header, if any, is converted into an HTTP_Content_Encoding property which is carried as a Solace API Property in the Solace message. This property's value is a string containing the HTTP Content-Encoding value verbatim.
The HTTP Content-Type header, if any, is converted into an HTTP_Content_Type property which is carried as a Solace API Property in the Solace message. This property's value is a string containing the HTTP Content-Type value verbatim.
HTTP Content-Encoding and Content-Type may be parameterized (for example, Content-Type: text/plain; charset=utf-8); any such parameters are also captured in value of the user property in the Solace message.
The length of the HTTP Content-Encoding and Content-Type values is limited to 252 bytes each, including parameters.

For more information on how to set and access these parameters in other Solace APIs refer to Interactions with Solace Messaging APIs.

Solace Message Type Mapping to HTTP Content-Type

When a Solace PubSub+ event broker converts a Solace message to an HTTP message, as either an HTTP POST request to a REST consumer, or an HTTP POST response to a REST producer in a request/reply message exchange, the event broker adheres to the following rules to set an appropriate HTTP Content-Type and Content-Encoding header.

The following steps outline how the Content-Encoding HTTP header is set:

If an HTTP_Content_Encoding property is present as a Solace API Property in the Solace message and this property has a string value, the string value of this property is used as the HTTP message's Content-Encoding header value.
Otherwise, the sent HTTP message has no HTTP Content-Encoding header.

The following steps outline how the Content-Type HTTP header is set:

If an HTTP_Content_Type property is present as a Solace API Property in the Solace message and this property has a string value, the string value of this property is used as the HTTP message's Content-Type header value.
Otherwise, if the HTTP Content-Length is zero (that is, no HTTP payload), the HTTP message has no HTTP Content-Type header.

Otherwise, the HTTP Content-Type is automatically determined by the event broker based on the type of the Solace message as outlined in the following table:

Solace Message Type	HTTP Content-Type
Solace text message	If the message contents are in the event broker SMF message XML attachment: `Content-Type: text/xml` Otherwise: `Content-Type: text/plain`
Solace binary message	`Content-Type: application/octet-stream`
Solace Map message	Unsupported for REST producers.
Solace Stream message	Unsupported for REST producers.
All HTTP error responses returned to REST clients	`Content-Type: text/xml`

For more information on how to set and access these parameters in other Solace APIs refer to Interactions with Solace Messaging APIs.

The event broker does not check that HTTP_Content_Encoding or HTTP_Content_Type values result in valid HTTP headers. It is the responsibility of message publishers to set appropriate values for these fields.

There are not any specific limitations on the length of HTTP_Content_Encoding or HTTP_Content_Type values. These fields are encoded in the Solace message as custom user properties and must fit within the maximum values of the REST API for custom user properties.
A Solace message that contains both an XML attachment and a binary attachment is unrepresentable in REST. This message format is an abnormal use of the Solace SMF message format. Applications should send a message with contents in the binary attachment or the XML attachment but not both. The Solace event broker will transform any Solace messages with both an XML attachment and a binary attachment to an HTTP message with no body, and Warning and Solace-Warning HTTP headers indicating the specifics of the problem.

Content Type when Sending Between REST Producers and REST Consumers over Solace

Given the above rules governing how the HTTP headers Content-Type and Content-Encoding are encoded into a Solace message and decoded from a Solace message, it is possible to preserve these headers end to end between REST producers and REST consumers over Solace HTTP REST messaging. When an HTTP message is published to Solace, these values will be encoded as user properties in the resulting Solace message format. When the event broker converts this message back to an HTTP message, as either an HTTP POST request to a REST consumer or an HTTP POST response to a REST producer in a request/reply message exchange, these Solace message properties will again be used as the HTTP headers of the POST.

Solace Message Custom Properties

HTTP headers starting with Solace-User-Property can be used to specify properties that are carried end-to-end through the event broker. These properties are encoded as user properties in the resulting Solace message.

The HTTP headers must adhere to the following format:

Solace-User-Property-<name>: <value> [; type=<type>]

Violations of the above rules result in the event broker rejecting the entire HTTP message with the appropriate error indication.

Solace User Property <Name>

The custom properties name is included in the HTTP header name after the Solace-User-Property prefix separated by a - as indicated by the format above.

Custom header names must produce valid HTTP header names. The <name> string provided is encoded to the Solace message exactly as found in the HTTP Request message. That is, character case is maintained. The same is also true for decoding the <name> from a Solace Message. The custom user property name is used exactly as found in the Solace message.

For special characters, percent encoding can be used to create valid HTTP header names and this percent encoding is interpreted by the event broker when it generates the resulting Solace message.

The event broker always sends percent-encoded header names.

Setting two properties with the same key name (duplicate key names) is unsupported and the behavior is undefined. Do not send HTTP messages with two Solace User Properties with the same key name.

Solace User Property <Type>

The type parameter is optional. By default all Solace User Properties in a REST message are assumed to have a type "string". The following is a list of valid types:

string, wchar, bool, int8, int16, int32, int64, uint8, uint16, uint32, uint64, float, double, null

The following types supported in other Solace APIs are not supported in Solace REST messaging:

SmfMessage, Destination, Map, Stream, byte[]

Type values are case-insensitive. For a type of null, the value is ignored. Any Solace User Property types other than those above result in the entire HTTP header being ignored.

The event broker omits the type field for all HTTP Solace User Properties of type string.

Value Field

The Value field is interpreted in the context of the type value. The following rules outline restrictions:

Values of string type can contain any UTF-8-encoded characters to a length limit of 252 bytes.
Values of wchar type represent any unicode value.
Values of int8 type are signed 8 bit values.
Values of int16 type are signed 16 bit values.
Values of int32 type are signed 32 bit values.
Values of int64 type are signed 64 bit values.
Values of uint8 type are signed 8 bit values.
Values of uint16 type are unsigned 16 bit values.
Values of uint32 type are unsigned 32 bit values.
Values of uint64 type are unsigned 64 bit values.
All int* or uint* values can be specified in hexadecimal (prefix 0x), octal (prefix 0) or decimal (first character 1 to 9.)1
Value of float type are a 32-bit floating point number specified as decimal numbers (including optional decimal point or exponent) or hexadecimal numbers (prefix 0x).2
Values of double type are 64-bit floating point numbers specified as decimal numbers (including optional decimal point or exponent) or hexadecimal numbers (prefix 0x).3
Float or double values which cannot be exactly represented by IEEE 754 binary32 or binary64 values, respectively, may be slightly modified due to precision errors when sent by the event broker in an outgoing Solace-User-Property HTTP header.
Values of type bool are canonically true or false, but the event broker also accepts numeric values or strings. The case-insensitive token false, the empty string, or any numeric value equal to zero are equivalent to false; anything else is equivalent to true.
If a string type value field is omitted, the value defaults to the empty string.
If a numeric value field is omitted, the value defaults to 0.
The event broker rejects any HTTP message where a numeric Solace-User-Property does not fit within its specified type.

Solace User Property field values must be encoded in one of two ways:

double-quoted strings ("quoted-string" in the ABNF of RFC7320 appendix B)
bare (i.e. unquoted) percent-encoded strings.

When sending REST messages, the event broker always sends Solace User Property headers using percent-encoded strings.

Examples

Some examples of custom user properties are:

Solace-User-Property-UserStringProp1: UserPropVal1
Solace-User-Property-integer-example: 1234; type=int32
Solace-User-Property-currency: %e2%82%ac50.40
Solace-User-Property-spaced: "Inner spaces only"

In JMS these properties would be set and retrieved from a message as follows:

// Setting
TextMessage msg = session.createTextMessage();
msg.setStringProperty("UserStringProp1", "UserPropVal1");
msg.setIntProperty("integer-example", 1234);
msg.setStringProperty("currency", "€50.40");
msg.setStringProperty("spaced", "Inner spaces only");

// Retrieving
msg.getStringProperty("UserStringProp1");
msg.getIntProperty("integer-example");
msg.getStringProperty("currency");
msg.getStringProperty("spaced");

Conversion from HTTP to Solace Messages

When the event broker converts a received HTTP message to a Solace SMF message, Solace-User-Property tuples are converted to entries in user properties map of the Solace message. The conversion preserves each HTTP user property name, type, and value.

If an HTTP message cannot successfully be encoded as a Solace message, the event broker discards the message and sends the REST producer an error notification.

Conversion from Solace Message to HTTP

When converting from a Solace message to a REST HTTP message, the event broker converts user property fields of the Solace message to a Solace-User-Properties HTTP header.

If a Solace message cannot be completely encoded into an HTTP message, either because:

there are more than 96 user property fields in the Solace message
some of the user property fields in the Solace message are of unsupported types

Then the problematic fields are omitted from the HTTP headers, and the event broker includes Warning and Solace-Warning HTTP headers in the HTTP message indicating the nature of the problem.

Other HTTP Header Fields

In Microgateway mode, the Solace event broker attaches any received HTTP header fields not otherwise mentioned to the Solace message's user properties metadata. The HTTP header field <header_name>: <header_value> is in the user property with key JMS_Solace_HTTP_field_<header_name> and string value <header_value>. There is no particular restriction on the sizes of these HTTP header fields attached to the Solace message's user properties metadata, but such metadata does count against the overall Solace message size limits. A maximum of 128 Solace message's user properties metadata with key JMS_Solace_HTTP_field_<header_name> is converted to HTTP headers with field name <header_name>: in an HTTP message sent by a Solace event broker.

In messaging mode, the Solace event broker ignores and discards any received HTTP header fields not otherwise mentioned in this document.

Solace Messaging User Property Metadata

In the Microgateway-mode conversion between HTTP messages and Solace messages, the following HTTP information is stored in Solace message user properties. An SMF client or AMQP client exchanging messages with a Solace event broker could manipulate these user properties.

User Property Key	Description
`JMS_Solace_HTTP_method`	When the Solace event broker sends or receives an HTTP request, this user property contains the HTTP request method.
`JMS_Solace_HTTP_target_scheme`	When the Solace event broker receives an HTTP request whose request-target is in absolute form, this user property contains the request-target's scheme (either `http` or `https`). This value has no effect on whether the Solace message is eventually forwarded by the Solace event broker over a plain-text or TLS connection.
`JMS_Solace_HTTP_target_host`	When the Solace event broker receives an HTTP request whose request-target is in absolute form, this user property contains the request-target's host. If the Solace event broker is sending this message as an HTTP request to an RDP consumer HTTP server through a queue binding whose `replace-target-authority` is disabled, then the HTTP request-target is in absolute form with this user property value as its host value, and as the value of the HTTP Host: header.
`JMS_Solace_HTTP_target_port`	When the Solace event broker receives an HTTP request whose request-target is in absolute form with an explicitly-specified port, this user property contains the request-target's port. If the Solace event broker is sending this message as an HTTP request to an RDP consumer HTTP server through a queue binding whose `replace-target-authority` is disabled, then the HTTP request-target is in absolute form with this user property value as its port value, and as the port value of the HTTP Host: header.
`JMS_Solace_HTTP_target_path_query_verbatim`	This user property contains the request-target's path and query with the leading '/' stripped. That is, a request-target of "/" is represented in this user property value as the empty string. Any percent-encoding is unchanged between the request-target and this user property. If the Solace event broker is sending this message as an HTTP request to an RDP consumer, this user property supplies the request-target's path and query.
`JMS_Solace_HTTP_field_<header_name>`
`JMS_Solace_HTTP_status_code`	When the Solace event broker sends or receives an HTTP response, this user property contains the HTTP status code. If this user property is absent, the status code defaults to `200`.
`JMS_Solace_HTTP_reason_phrase`	When the Solace event broker sends or receives an HTTP response, this user property contains the HTTP reason phrase. If this user property is absent, the reason phrase defaults to `OK`.
`JMS_Solace_HTTP_max_forwards`	When the Solace event broker receives an HTTP request with an HTTP Max-Forwards header, the message's `JMS_Solace_HTTP_max_forwards` user property contains the value of that Max-Forwards header minus 1. If the received HTTP request does not contain an HTTP Max-Forwards header, this user property is omitted. When the Solace event broker sends a message with this user property as an HTTP request, the HTTP request's Max-Forwards header is set to the value of this user property.

Provide feedback