☰
Navigation :

RestServerApp

REST Server Application Configuration

The N2SVCD REST Server Application listens for inbound REST.

The REST Server Application does not process any user content itself. It exists only as an agent to receive requests on behalf of another application.

Typical uses of the RestServerApp are:

See the N2SVCD Configuration Overview for more information on how the REST Server Application interacts with other components.

The following configuration is used to create a REST Application TCP Server instance.

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="REST-SERVER" module="RestServerApp">
      <include><lib>../apps/rest_s/lib</lib></include>
      <parameters>
        <parameter name="trace_level" value="1"/>
        <parameter name="local_port" value="8118"/>
        <parameter name="quirks_mode" value="generic"/>
      </parameters>
      <config>
        <handlers>
          <handler method="GET" application="Logic"/>
        </handlers>
      </config>
    </application>
    ...
  </application>
  ...
</n2svcd>

Configuration Details

The application element attributes for a REST Server Application instance may include the below.

For details of the various parameter types used, refer to Common Configuration.

Parameter Name Type XML Type Description
See: Common Application configuration
See: TCP Application configuration
module String Attribute [Required] RestServerApp
include.lib String Element [Required] ../apps/rest_s/lib
parameters Array Element [Required] As per Common Configuration Application parameters.
"edr_enabled" - - This value is ignored; the REST Server Application Application does not support writing EDRs.
"socket_mode" String Attribute The REST Server Application supports only listen (TCP Server).
(Default = listen)
"local_port" Positive Integer Attribute As per common TCP configuration for local_port.
(Default = 8080)
"ping_interval" - - This value is ignored; the REST Server Application does not support sending of ping messages.
"quirks_mode" String Attribute The integration quirks to apply to server connections, as described in Quirks Modes.
(Default = generic)
config Object Element Container for extended configuration for this application.
.handlers Array Element Array of handler elements, rules for selecting the owning Application for inbound REST requests.

REST Handlers

Handler rules define which application is used to process inbound REST Requests. Each handler Object in the config.handlers Array is configured as follows.

Parameter Name Type XML Type Description
method String Attribute The inbound HTTP method, e.g. GET, PUT, POST, DELETE, etc.
(Default = Handle all methods)
path String Attribute A path from the URL, exact matched against the path of the inbound request. Only one of path or path_prefix may be specified.
path_prefix String Attribute A path from the URL, prefix matched against the path of the inbound request. Only one of path or path_prefix may be specified.
application String Attribute [Required] The name of the application that should process matching messages. This will normally refer to a LogicApp instance.

The handlers will be checked in order, and the first matching handler will be used.

Quirks Modes

The REST Server Application may operate in a “quirks mode”, which controls the way in which arguments are passed into local representation.

The available quirks modes are listed below.

Quirks Mode (Generic)

The generic value of quirks_mode is a default “normal” HTTP interpetation of URI query string (the part following “?” in the URI), which is provided as an initial starting point for integrating with other end-points.

Quirks Mode (URI path parameters)

The uri_params value of quirks_mode is required when the URI path itself contains both the command and a single parameter for the command.

For example, to trigger the command foo with the parameter bar, the URI path recieved would be:

http://rest-server-app/foo/bar

When constructing the REST-S-REQUEST then:

The result is that the corresponding Logic script selection within the RestLuaAgent will find a final path element of foo instead of bar, and hence will execute the logic script foo.[lua|lc] instead of the logic script bar.[lua|lc].

This is typically what we desire when using this interpretation of REST URIs.

The equivalent generic request would be:

http://rest-server-app/foo?foo=bar

Message Handling

In addition to the common Application management messages, the RestServerApp uses the following messages: