Managing and Monitoring over REST

Apama provides a Representational State Transfer (REST) HTTP API with which you can monitor Apama components. The monitoring capabilities are available to third-party managing and monitoring tools or to any application that supports sending and receiving XML documents, or receiving JSON documents, over the HTTP protocol.

Apama components expose several URIs which can be used to either monitor or manage different parts of the system. Some are exposed by most Apama components. These are the generic management URIs. Some are exposed only by specific types of components. For example, a correlator running on the default port of 15903 will expose a URI at http://localhost:15903/correlator/status. If an HTTP GET is issued against the URI, the correlator will return a document with the current status of the correlator. The format of this document is depicted by the header set in the request, that is, application/xml for XML and application/json for JSON.

Most URIs are purely for informational purposes and will only respond to HTTP GET requests, and interacting with them will not change the state of the component. However, some URIs allow the state of the correlator to be modified. They will respond to one or more of the other HTTP methods, but may only support XML and not JSON. For example, the /logLevel URI will accept an HTTP PUT request containing an XML document describing what the log level of the component should be set to. However, the /request URI will accept JSON or XML documents via PUT.

All requests and responses over these interfaces have the same, simple elements:

  • In XML, these elements are:

    • prop
    • map
    • list All elements have a name attribute. The prop element simply represents a name-value pair with the name contained in the name attribute and the value being the content of the element. The map element is an unordered list of named elements which might be any of the three sets of elements, though it is quite typically simply a map of prop elements. See the /info URI as an example. The list is very similar to the map element except that here the order is typically regarded as significant. All responses from these URIs have a top-level element with the name apama-response and similar all requests which are sent to these URIs should have a top-level element with the name apama-request. If there is an error, then a response called apama-exception will be returned.

  • In JSON, these elements are:

    • map {}
    • list [] All elements have a name-value pair. Name and value are separated by a colon (:) with the name to the left and the value to the right of the colon. The map element, which is represented by curly brackets, is an unordered list of named elements which might be any of map or list elements. See the /info URI as an example. The list element, which is represented by square brackets, is very similar to the map element except that here the order is typically regarded as significant. If there is an error, then a response with the error message is returned, for example, {"apamaErrorMessage":"Not found"}.

For both formats, the /connections URL is a good example of all these elements being used together:

  • In XML, the top-level element is a map which has two children, both list elements, called senders and receivers. Each list contains a map element for each sender and receiver. Each sender or receiver has a set of prop elements.
  • In JSON, the top-level element is a map {} which has two children, both list [] elements, called senders and receivers. Each list contains a map {} element for each sender and receiver. Each sender or receiver has a set of name-value pairs.

For detailed information on the supported URIs, see the API reference for Component Management REST APIs.

Two examples are provided below, one for JSON and another for XML. Each example shows only a possible hierarchy of a response. To get the actual format of the response for each request, it is recommended that you actually make the request.

Example for JSON:

{
  "Key1": [
    {"Key1.1.1":"Value1.1.1","Key1.1.2":"Value1.1.2"},
    {"Key1.2.1":"Value1.2.1","Key1.2.2":"Value1.2.2"}
   ],
  "Key2":[],
  "Key3":
   [
    {"Key3.1.1":"Value3.1.1","Key3.1.2":[]}
   ],
  "Key4":[]
}

Example for XML:

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="/resources/transform.xslt"?>
<map name="apama-response">
  <list name="Key1">
    <map name="Key1.1">
      <prop name="Key1.1.1">Value1.1.1</prop>
      <prop name="Key1.1.2">Value1.1.2</prop>
    </map>
    <map name="Key1.2">
      <prop name="Key1.2.1">Value1.2.1</prop>
      <prop name="Key1.2.2">Value1.2.2</prop>
    </map>
  </list>
  <list name="Key2"/>
  <list name="Key3">
    <map name="Key3.1">
      <prop name="Key3.1.1">Value3.1.1</prop>
      <list name="Key3.1.2"/>
    </map>
  </list>
  <list name="Key4"/>
</map>