HTTP protocol
Decision Server Insights can receive and send events in the form of HTTP or HTTPS requests, using the POST method.
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. |
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 either a schema-defined (TYPED_XML) message, or a message that is classified and transformed by an inbound binding definition. 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 contains either a schema-defined (TYPED_XML) message or a generic (GENERIC_XML) message; message transformation is not supported. 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 did not represent a valid event. 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 it reaches 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.
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 in 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 |
The outbound HTTP endpoint sends a POST request using the specified Content-Type. 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.