About the HTTP server transport

The HTTP server is a transport for use in connectivity plug-ins which external services can connect to over HTTP/REST. It can handle both an HTTP submission-only API which delivers events to the correlator and a REST request/response API where the responses are controlled from EPL. In addition to this, it can serve static files. It also allows support for TLS alongside HTTP basic authentication.

The HTTP server transport can decode HTTP requests encoded with gzip or deflate compression format. It also supports HTML form decoding and can decode multipart/form-data or application/x-www-form-urlencoded media types to a dictionary payload.

This transport provides a dynamic chain manager (the chain manager for each host/port is configured by an entry under dynamicChainManagers in the YAML configuration file) which creates chains automatically whenever an HTTP client connects to that host/port. For the HTTP server transport, there must be exactly one chain definition provided in the dynamicChains section of the YAML configuration file. The EPL channel that incoming requests are sent to is specified in the configuration of the dynamicChains, by rules in the mapperCodec section that set the metadata.sag.channel.

HTTP requests are received by the transport and sent to the chain where they are mapped to EPL events as described in Mapping events between EPL and HTTP server requests. Whether the response to the HTTP request is generated automatically or by the EPL application is controlled as described in Handling responses in EPL.

Persistent connections to the server are supported for multiple requests. Details of the individual requests are configured through the events sent to the chain. The HTTP server supports HTTP version 1.1 and TLS version 1.2 and above.

The HTTP server is designed to listen for REST services and supports all GET, POST, PUT and DELETE operations which have been specified in the configuration file. Other than GET requests served by static files, all requests are treated identically.

The samples/connectivity_plugin/application/httpserver directory of your Apama installation includes a sample which demonstrate how to use the HTTP server connectivity plug-in to send and receive HTTP requests containing events into the correlator through various configurations. See the README.txt file included with the sample for complete instructions on how to run the sample application.

Swagger or OpenAPI 2.0 (OAS) is an open standard for defining REST APIs originally developed by the SmartBear company. The OAS, and the open source tools available, can be used to design, document, test and deploy the REST API for an application. The 3.0 specification (https://swagger.io/specification/) is being released at the time of writing, but it is backward compatible with the stable 2.0 specification (https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) used to author our small sample.

The specification allows for the Swagger definition to be written in either YAML or JSON. We have chosen to deliver the Swagger definitions as JSON to disambiguate them from configuration files when they are deployed in the same directory. It is easy to convert between the two formats.

The specification allows the author to define the transport mechanism, data, requests, responses and to document the required REST API. There is an open source suite of tools that take this definition and allow it to be edited, documented and code to be generated (https://swagger.io/tools/). The editor is available as a web application or stand-alone and provides a representation of the definition that is interactive and informative. The editor allows the user to convert to and from JSON, generate server or client code, and generally manipulate the definition in intuitive and useful ways.

The transport returns a response to the client. If responses are automatically generated, we return a "202 Accepted" response after HTTP parsing, but before processing by the correlator, to indicate that a failure may still occur later in processing the event. If the response is handled by EPL, the response code is defined by the EPL application and configuration. If there is a failure in parsing the HTTP part of the request, an error code is returned instead.

Code	Reason
202 Accepted	On a successful submission, this indicates that while we've accepted it, processing will occur later and we cannot guarantee completion.
401 Unauthorized	We have enabled HTTP basic authentication and the user either does not supply an Authorization header or it is incorrect.
405 Method Not Allowed	The request has a method we do not support (depending on what is configured in the configuration file).
400 Bad Request	Any other error we can conclusively say is due to a malformed request.
415 Unsupported Media Type	The client has sent an unsupported Content-Encoding header.
429 Too Many Requests	If too many authentication failures occur (maxAttempts), then requests are throttled for the defined cool-down period (coolDownSecs) to protect the running correlator. See Configuring the HTTP server transport for more information on the configuration options maxAttempts and coolDownSecs.
500 Internal Server Error	Any other error which occurs before we send the event into the correlator.
504 Gateway Timeout	The EPL application did not respond within the configured timeout.
Other HTTP response codes	Errors returned by the EPL application.