Apama 10.3 | Apama Documentation | 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 HTTP requests and deliver the contained events to the correlator, which will return acknowledgment of the requests. In addition to this, it can serve static files. It also allows support for TLS alongside HTTP basic authentication.
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.
To send a request, you send HTTPRequest events to that channel, where these events are correctly mapped as described in Mapping events between EPL and HTTP server requests. The acknowledgment response is sent back by the same chain instance on the same channel.
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.
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.
HTTP response codes
The transport returns a response to the client after HTTP parsing, but before processing by the correlator. We return a "202 Accepted" response to indicate that a failure may still occur later in processing the event. 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.
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.
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.

Copyright © 2013-2018 | Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors.