Solace REST HTTP Message Encoding

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

HTTP Request-Target

The Solace message 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 message broker acts as an HTTP server, it receives REST HTTP requests from message producers. The Solace message broker converts the received HTTP request-target into a Solace messaging topic, on which it will route the message.

Conversely, when the Solace message broker acts as an HTTP client, in a REST delivery point (RDP), it will construct 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 Message Broker HTTP Server

When the Solace message 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 message broker will enqueue the message from the HTTP POST request into the message-spool queue named queue-name.

  • /TOPIC/topic-string

    The Solace message broker will publish the message from the HTTP POST request to the topic topic-string.

Solace Message Broker RDP to a REST HTTP Consumer Server

When the Solace message 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 Message Broker HTTP Server

When the Solace message broker receives an HTTP request from a REST HTTP producer client, the Solace message broker will publish 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 message broker uses to publish the message.

The Solace message 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 message 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 Message Broker RDP to REST HTTP Consumer Server

When the Solace message 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 message 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 message 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 message 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+ message 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 Client Authentication Management for details related to 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 message 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.

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 message 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+ message 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 message broker receives an HTTP request with Forwarded or X-Forwarded-For header(s), and the message broker RDP subsequently sends that message as an HTTP request, the message 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 message broker.

Max-Forwards: integer

In messaging mode, the message broker ignores this header.

In Microgateway mode, if the message 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 message broker subsequently sends that message as an HTTP request, the HTTP request will also have a Max-Forwards header with its value decremented by one.

Transfer-Encoding: chunked

A Solace PubSub+ message broker supports HTTP POST requests sent using chunked transfer encoding as outlined in RFC 7230. A Solace message broker will ignore and discard any trailing headers.

User Agent: string

This header is displayed when you issue a show client details CLI command on the message broker.

Standard HTTP Headers on HTTP Responses from Solace

A Solace PubSub+ message 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 message broker always sends a Cache-Control: no-cache header field.

In Microgateway mode, any Cache-Control header field is passed transparently through the Solace message broker as Solace message metadata.

Content-Encoding

In both messaging and Microgateway modes, the Solace message broker will send 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 message broker will send 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+ message 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, 3230 or 3560). The version is the Solace PubSub+ version that the message broker is running (for example, 7.x.x.x).

In Microgateway mode, any Server header field is passed transparently passed through the Solace message 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 message broker as Solace message metadata.

Warning: 299 - “string”

Optional, as per RFC 7234. If present, indicates that the message 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+ message broker to a RDP consumer HTTP server, the message broker provides the following standard HTTP header fields:

Header Key/Value

Description

Authorization: Basic base64(configured_
authentication_string)

If the message broker is configured to use basic authentication when establishing outgoing connections to RDP consumer HTTP servers, the message broker will provide the Authorization header on each HTTP request. If basic authentication is not configured for outgoing connections to RDP consumer HTTP servers, the message broker will not provide the Authorization header field.

Cache-Control: no-cache

In messaging mode, the Solace message broker always sends a Cache-Control: no-cache header field.

In Microgateway mode, any Cache-Control header field is passed transparently through the Solace message 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 message broker will send 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+ message broker sets this header based on the message type of the message 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 message broker as Solace message metadata.

In messaging mode, the platform component indicates the Solace platform type (for example, 3230 or 3560). The version is the Solace PubSub+ version that the message broker is running (for example, 7.1.x.x).

Warning: 299 - “string”

Optional, as per RFC 7234. If present, this warning indicates that the message 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+ message 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 message broker will send 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 message 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 message broker will also attach any Content-Type to the Solace message metadata.

Transfer-Encoding: chunked

The message broker supports HTTP responses sent using chunked transfer encoding as outlined in RFC 7230. The message broker will ignore and discard 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 message broker takes some local action described below when it receives HTTP messages with these headers, Conversely, the Solace message 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 message 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 message broker automatically generates a unique Solace message broker client name.

To set the message 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 message 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 message broker will follow 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 message broker to an RDP consumer HTTP server.

Solace-Client-Description: Solace String

(See Header Value Encoding - Solace String)

Specifies the message broker client description for the HTTP requests from an HTTP client. A Solace PubSub+ message broker client description field is displayed in Solace message broker admin screens; it provides extra details about the client.

To set the Solace message 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 message 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 message 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 message broker encodes this destination in the Solace message so that Solace messaging APIs (including the JMS implementation) will 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 Message 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 message broker must up to the specified timeout value for an application reply which the Solace message broker will encode 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 message broker will send 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 message broker is to wait forever for an application reply. The HTTP connection must be closed to unblock in a failure scenario.

When the Solace message broker sends an HTTP request to an RDP consumer HTTP server, the Solace message broker will set 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 message 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 will be carried end-to-end through the message 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 send the Solace message broker an HTTP request. The Solace message 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 message broker. The Solace message 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 message 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 message broker for a request-reply message exchange pattern, and the HTTP client does not provide a Solace-Message-ID header, the Solace message broker will synthesize a unique message ID for the request message. When the Solace message broker synthesizes a message ID, it will be in the form ID:Solace-<unique_val>, where <unique_val> is a unique 64-bit integer expressed in hexadecimal. The Solace message broker will attach the message ID, and correlation ID if any, as metadata to the Solace request message. The Solace message broker will also attach 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 message 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
  • 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 message 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 message broker sends a Solace message as an HTTP request to an RDP consumer HTTP server, the Solace message 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 message broker receives the HTTP response from the RDP consumer HTTP server, it creates a Solace reply message corresponding to the HTTP response. The Solace message 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 message 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 message 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 message broker sends the HTTP response to the HTTP client, any message ID and correlation ID metadata in the Solace message will appear 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.

Solace PubSub+ Message Broker Message Field Defaults for REST Messages

A Solace PubSub+ message 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 message broker. In doing this, the message broker will assign 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 will 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 will not be flagged as deliver-to-one (DTO) (that is, this field will have a value of false).

Sender ID

Messages received from a REST producer will not have a sender ID field set, and the field will not be present in Solace messages.

JMS Message Priority

Messages received from a REST producer will not have a JMS message priority field set, and the field will not be 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 message 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 will be omitted from the HTTP message. Further, the HTTP message will contain Warning and Solace-Warning headers indicating that HTTP body has been omitted and why.

Note:  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 messages to the message broker or a REST consumer sends a reply message back to the message broker in the body of an HTTP response, it must correctly set the Content-Type in the HTTP headers to provide a directive to the message broker as it creates the resulting Solace message for forwarding. When Content-Type is not present, the message broker assumes that the contents are binary, and Solace binary messages result. If Content-Type is present, and it does not map to Solace text messages as outlined in the following table, then the contents are assumed to be binary and will result in Solace binary messages. The following tables outline the mapping of Content-Type to Solace message types.

HTTP Content-Type

Solace Message Type

text

text/*

application/json

application/soap+xml

application/xml

Solace text message.

application/octet-stream

(all other values)

(HTTP Content-Encoding present)

Solace binary message. By default, a Solace PubSub+ message broker treats the content of a message as binary unless it is specifically indicated to be text.

If a Content-Encoding is specified, then the message broker will treat the contents as binary regardless of the HTTP Content-Type provided.

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:

  1. 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.
  2. 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.
  3. 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.
  4. The length of the HTTP Content-Encoding and Content-Type values is limited to 252 bytes each, including parameters.

Note:  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+ message 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 message broker will adhere 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:

  1. 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 will be used as the HTTP message’s Content-Encoding header value.
  2. Otherwise, the sent HTTP message will have no HTTP Content-Encoding header.

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

  1. 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 will be used as the HTTP message's Content-Type header value.
  2. Otherwise, if the HTTP Content-Length is zero (that is, no HTTP payload), the HTTP message will have no HTTP Content-Type header.
  3. Otherwise, if the HTTP Content-Type will be automatically determined by the message broker based on the type of the Solace message as outlined in the following Table.

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

HTTP Content-Type Mappings when Receiving from Solace

Solace Message Type

HTTP Content-Type

Solace text message

If the message contents are in the message 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

The message 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.

Note  
  • 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 message 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 message 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 will be carried end-to-end through the message 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 message 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 will be encoded to the Solace message exactly as found in the HTTP Request message. That is character case will be maintained. The same is also true for decoding the <name> from a Solace Message. The custom user property name will be 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 will be interpreted by the message broker when generating the resulting Solace message.

The message broker will always send percent-encoded header names.

Note:  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 have 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 will be ignored. Any Solace User Property types other than those above result in the entire HTTP header being ignored.

Note:  The message broker will omit the type field for all HTTP Solace User Properties of type string.

Value Field

Value values are 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 The message broker computes “int*” values using the standard C library function strtoll(), and “uint*” values using the standard C library function strtoull().
  • 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 The message broker computes “float” values using the standard C library function strtof().
  • Values of double type are a 64-bit floating point number specified as decimal numbers (including optional decimal point or exponent) or hexadecimal numbers (prefix 0x).3 The message broker computes “double” values using the standard C library function strtod().
  • 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 message broker in an outgoing Solace-User-Property HTTP header.
  • Values of type bool are canonically true or false, but the message 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 message broker will reject 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 message broker will always send 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 message 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 be successfully encoded as a Solace message it will be discarded by the message broker and the REST producer will receive an error notification.

Conversion from Solace Message to HTTP

When converting from a Solace message to a REST HTTP message, the message 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 will be omitted from the HTTP headers, and the message broker will include 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 message broker will attach any received HTTP header fields not otherwise mentioned to the Solace message's user properties metadata. The HTTP header field <header_name>: <header_value> will be 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> will be converted to HTTP headers with field name <header_name>: in an HTTP message sent by a Solace message broker.

In messaging mode, the Solace message broker will ignore and discard 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 message broker could manipulate these user properties.

User Property Key Description

JMS_Solace_HTTP_method

When the Solace message broker sends or receives an HTTP request, this user property will contain the HTTP request method.

JMS_Solace_HTTP_target_scheme

When the Solace message broker receives an HTTP request whose request-target is in absolute form, this user property will contain 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 message broker over a plain-text or TLS connection.

JMS_Solace_HTTP_target_host

When the Solace message broker receives an HTTP request whose request-target is in absolute form, this user property will contain the request-target's host. If the Solace message 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 will be 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 message broker receives an HTTP request whose request-target is in absolute form with an explicitly-specified port, this user property will contain the request-target's port. If the Solace message 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 will be 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 "/" would be 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 message broker is sending this message as an HTTP request to an RDP consumer, this user property will supply the request-target's path and query.

JMS_Solace_HTTP_field_<header_name>

 

JMS_Solace_HTTP_status_code

When the Solace message broker sends or receives an HTTP response, this user property will contain the HTTP status code. If this user property is absent, the status code defaults to 200.

JMS_Solace_HTTP_reason_phrase

When the Solace message broker sends or receives an HTTP response, this user property will contain the HTTP reason phrase. If this user property is absent, the reason phrase defaults to OK.

JMS_Solace_HTTP_max_forwards