Apama 10.15.0 | Connecting Apama Applications to External Components | Standard Connectivity Plug-ins | The HTTP Server Transport Connectivity Plug-in | About the HTTP server transport
 
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 and encode EPL responses or static files 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.
For more information on YAML configuration files, see Using Connectivity Plug-ins and especially Configuration file for connectivity plug-ins.
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.
Note:
The HTTP server connectivity plug-in does not support reliable messaging.
OpenAPI definitions
OpenAPI is an open description format for REST APIs. The OpenAPI Specification (OAS), and the related tools available from Swagger ( https://swagger.io), can be used to design, document, deploy and test the REST API for an application. The specification allows for API definitions to be written in either YAML or JSON.
Apama API definitions are supplied in JSON format to the OpenAPI/Swagger 3.0 specification.
HTTP response codes
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.
The various response codes that we currently support are described below.
Code
Reason
202 Accepted
Success response code for automatic responses. On a successful submission, this indicates that while we have accepted it, processing will occur later and we cannot guarantee completion.
400 Bad Request
Any other error we can conclusively say is due to a malformed request.
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).
413 Request Entity Too Large
The uncompressed payload is larger than defined with the maxRequestBytes configuration option. See Configuring the HTTP server transport for more information on this configuration option.
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.
503 Host Not Ready
The HTTP server received a request before the application called onApplicationInitialized() in the correlator. See Sending and receiving events with connectivity plug-ins for more information on this method.
504 Gateway Timeout
The EPL application did not respond within the configured timeout.
Other HTTP response codes
As defined by the EPL application and configuration.