HTTP protocol

Decision Server Insights can receive and send events in the form of HTTPS requests, using the POST method.

HTTP inbound message format and encoding

Table 1. HTTP inbound message format and encoding
Message format (from binding) Message type Message content Character encoding
application/xml or text/xml Content-Type: application/xml Message bytes parsed as XML. If present, the character encoding declared in Content-Type header is authoritative. Otherwise, the encoding in the XML directive is used.
Content-Type: text/xml Message text parsed as XML. If present, the character encoding declared in Content-Type header is authoritative. Otherwise, US-ASCII is used. The XML directive encoding is ignored.
application/json Content-Type: application/json Message text parsed as JSON. If present, the character encoding that is declared in the Content-Type header is authoritative. Otherwise, UTF-8 is used.
Decision Server Insights can receive events over two kinds of HTTP endpoint:
Inbound HTTP endpoint
A solution-specific endpoint that is defined in a solution connectivity definition and configured as part of solution deployment to an inbound connectivity server. An inbound HTTP endpoint expects a POST request that contains a message that conforms to the message format that is specified by the associated inbound binding definition. If the inbound binding specifies application/xml or text/xml, the message must either conform to an XML schema that represents an event type (TYPED_XML) or must be classified and transformed by the inbound binding definition. If the inbound binding specifies application/json, the message must contain a JSON representation of an event.
An inbound HTTP endpoint rejects messages that contain a Content-Type header that is incompatible with the inbound binding definition, and messages that contain invalid XML or JSON content. However, unlike the HTTP gateway, an inbound HTTP endpoint accepts and discards messages that contain valid XML or JSON documents nevertheless cannot be identified as instances of event types defined by the business model of the solution. The security of an inbound HTTP endpoint is controlled by the configuration of the inbound connectivity server and the solution connectivity deployment configuration. Secured endpoints require HTTPS requests and can have solution-specific authorization. Unsecured endpoints can accept HTTP requests.
HTTP gateway
An endpoint that is solution independent. HTTP gateway is enabled by the inclusion of the HTTP gateway feature in an inbound connectivity server or runtime server configuration. The HTTP gateway expects a POST request that represents an event in a supported format. If the Content-Type is application/xml or text/xml, the event must be represented by either a schema-defined (TYPED_XML) message or a generic (GENERIC_XML) message; message transformation is not supported. If the Content-Type is application/json, the event must be represented by a JSON message. The HTTP gateway rejects messages that contain an incompatible Content-Type header and messages that contain invalid XML or JSON content. Unlike an inbound HTTP endpoint, the HTTP gateway also rejects messages that cannot be identified as instances of event types defined by the business model of the solution. The security of the HTTP gateway is controlled by the configuration of the server. A user ID authorized to use HTTP gateway can submit events to any deployed solution. HTTPS request is required.

The success of a POST request to an inbound HTTP endpoint or HTTP gateway is indicated by an HTTP response status code. The following list contains the possible status codes and a description:

200
The message is delivered to the solution. Inbound connectivity and gateway processing is not synchronous with agent processing, so this status does not reflect whether an event is processed by an agent. If the inbound binding that is associated with an inbound HTTP endpoint and the agent descriptors of the solution identify a message as irrelevant, the message is discarded. Such a message is successfully delivered and discarded by the solution logic, and the resulting status code is 200.
400
The message was rejected because it is invalid. For example, the message contained invalid XML or JSON content. Further information can be found in the server logs. Do not attempt to resubmit the message until the problem is resolved.
503
The message is rejected because it cannot be delivered to the solution now. The solution might be inactive or reached a load limit. More information about why the message is rejected can be found in the server logs. You can resubmit the message later.
500
The message is not processed due to an unexpected failure. More information about the failure can be found in the server logs.
When an inbound HTTP endpoint or HTTP gateway returns one of the previously listed status codes, the response entity is an application/json object that contains one or more of the following fields:
status
An integer that mirrors the corresponding HTTP response status.
routingStatus
Only applicable to the HTTP gateway: A string that has the result of submitting the event to the solution, as defined by com.ibm.ia.common.RoutingStatus.
message
A high-level message that outlines why the delivery was unsuccessful. For more information, see the server logs.

The inbound HTTP endpoint listens for requests that use the POST method and a supported Content-Type. If delivery is successful, the HTTP response status is 200. Failed delivery is indicated by an appropriate HTTP response status code.

Note: When an XML or JSON message is delivered to an inbound HTTP endpoint or the HTTP gateway, the system allocates a unique internal identifier for the event that is submitted to the solution. Subsequently, if an identical message is delivered, an event with a new unique internal identifier is submitted.

HTTP outbound message format and encoding

Table 2. HTTP outbound message format and encoding
Message format (from binding) Message type Message content Character encoding
application/xml Content-Type: application/xml Message bytes contain XML content using UTF-8 encoding. The encoding is specified in XML directive. The Content-Type header includes character encoding declaration, UTF-8.
text/xml Content-Type: text/xml Message bytes contain XML content using in UTF-8 encoding. The encoding is specified in XML directive. The Content-Type header includes a character encoding declaration, UTF-8.
application/json Content-Type: application/json Message bytes contain JSON conent using UTF-8 encoding. The Content-Type header includes a character encoding declaration, UTF-8.

The outbound HTTP endpoint sends a POST request by using the specified Content-Type. If the outbound binding specifies application/xml or text/xml, the message conforms to the XML schema that represents the event (TYPED_XML), or is transformed according to the outbound binding definition. If the outbound binding specifies application/json, the message contains the JSON representation of the event. The outbound binding can also specify HTTP header values. An HTTP response status of 200 or 201 is interpreted to indicate that the message was delivered successfully. If the HTTP response code represents a failure, or if a network problem occurs, the message delivery is deemed to have failed.