Configuration

Overview

Each web-services service is first configured with the below basic structure:

{
    "web-services-io": {
      "handler": "nz.co.nsquared.slee.webservices.WebServicesVerticle",
      "instance-count": 1,
      "configuration": {
          "template-paths": "/opt/nsquared/jslee/etc/templates/webservices",
          "routers": [
            // How requests are routed, both incoming and outgoing
          ],
          "endpoints": {
            "client": [
              // client endpoints
            ],
            "server": [
              // Server endpoints
            ]
          }
      }
    }
}

Common service configuration items are available for all JSLEE services. The following are the web-services specific configuration items:

Field Type Required? Default Description
template-paths String Yes - The base path for the templates that will be used by the web-services engine.
routers Array Yes (empty) Configuration for where to send requests received by the service.
endpoints.client Array No (empty) The HTTP servers to connect to (as a HTTP client)
endpoints.server Array No (empty) The HTTP servers to operate, for clients to connect to.
send-json-readable-body Boolean No false Whether the JSON sent (when JSON is sent, e.g. as part of REST requests) should be readable, or should be sent with whitespace removed.

Template Configuration

The web services service of the JSLEE uses the FreeMarker templating solution for all outgoing templates. Internally, the JSLEE will request HTTP requests sent by providing only the template name and variables. It is the responsibility of the web services verticle to generate the full HTTP body, based on templates.

The following configuration is applied to FreeMarker:

Routes

The JSLEE web services verticle, when running a HTTP server, is designed to process incoming HTTP requests efficiently, passing them to the appropriate business logic component that is running as a separate JSLEE service within a JSLEE cluster (single node, or a cluster of multiple nodes).

To achieve this, one or more message routers must be defined in the web services configuration, in the routers array. Each object in this array is a unique router which may be referenced by one or more HTTP server (defined in the endpoints.server section of the configuration).

A single-route router can be defined as:

{
  "router-name": "selfcare-router",
  "rest": [
    {
      "handler-address": "business-logic",
      "routes": [
        {
          "url": "/selfcare/balances"
        }
      ]
    }
  ]
}

In this example configuration, the named router selfcare-router has had the handler defined using the handler-address configuration option. The handler is the JSLEE address (service, or service + endpoint) that will handle the message.

The routes within a single router determine the HTTP URL paths that will be monitored for incoming traffic. The HTTP server performs a basic level of verification on each incoming HTTP requests, ensuring that the HTTP request is made to a URL with an associated route.

If an incoming HTTP request does not have a matching route within the associated router, then a HTTP failure is returned immediately and the request is not passed on to the handler-address based handler.

The following configuration fields are available for each router:

Field Type Required? Default Description
router-name String Yes - The name the router will be known by, for use in the endpoints section of the configuration in the server’s configured router field.
rest Array No - The group of URLs which will be handled as REST endpoints, along with the JSLEE address that will be used for processing incoming requests.
soap Array No - The group of URLs which will be handled as SOAP endpoints, along with the JSLEE address that will be used for processing incoming requests.

For each rest or soap route, the following fields are available:

Field Type Required? Default Description
handler-address String Yes - The JSLEE address (service, or service + endpoint) that will be sent the message to handle the request.
routes Array Yes - The list of HTTP URLs (routes) that will be handled by this router as incoming requests. All messages not matching at least one route will be rejected. The order of routes matters - earlier routes should be more specific than routes that appear later in the list.

and finally, for each routes object:

Field Type Required? Default Description
url String Yes - The URL path to match. Variable parts (e.g. MSISDNs, or IDs), can be included using : as a prefix, e.g. /account/:accountId.
methods Array No [ “GET” ] The list of HTTP methods to listen on. This may be used to restrict the type of incoming HTTP request that may match successfully. This must be an array of values GET, POST, PUT, or DELETE.

Endpoints

The JSLEE web services defines its endpoints within a hash (unlike most services, which define endpoints within an array). Within the “endpoints” hash are two keys, client and server.

Client Endpoints

A client endpoint is configured with the following basic elements:

{
    "name": "TAS",
    "service-type": "REST",
    "connection": {
      "port": 8080,
      "host": "tas.nsquared.co.nz"
    }
}

To configure a client, the following configuration options are available:

Field Type Required? Default Description
name String Yes - The name to know the client as. This forms the endpoint name for the JSLEE message bus, and must be unique within the JSLEE service. Other services will use this name when sending requests over this client connection to a HTTP server.
service-type String Yes - Either the word SOAP or REST (in capitals). Defines whether the HTTP connection is expected to send SOAP or REST requests. While most of the template format is derived from the related template, SOAP based connections require some additional work by the service.
connection Object No - Connection information for how to connect to the HTTP server that must be used by this client. If connections is not specified, connection must be.
connections Array No - An array of connection information for how to connect to the HTTP server that must be used by this client. The array of connections is used in round-robin mode for managing traffic requests. If connection is not specified, connections must be.

Connection information, defined using connection or connections, must define at least a host and port to connect to. Additional options can be injected using web-client-options:

Field Type Required? Default Description
host String No - The IP address, or hostname, to connect to. If not specified, the default Vert.X configuration options for the host must be used.
port Number No - The port to connect to. If not specified, the default Vert.X configuration options for the port must be used.
web-client-options Object No - Additional options for the client connection (both TCP and HTTP oriented)

Web Client Options

A HTTP Web Service connects to a web server using a Vert.X HTTP client. HTTP web client options can be given to the system using the web-client-options configuration object, as part of a connection object (possibly within a connections array).

The detailed options list is available on the Vert.X website in the web client options JavaDoc. This is also documented in the JSLEE TCP options section of this technical guide.

An example web-client-options might include a default-request-timeout-ms field, which is a custom field for the JSLEE web service:

{
  "default-request-timeout-ms": 750
}

Key configuration options used by the web services service are:

Field Type Required? Default Description
default-request-timeout-ms Number No 15000 The number of milliseconds to wait for a response to a request, before timing out (and possibly retrying on a separate connection). This is 15s by default.
connect-timeout-ms Number No 5000 The number of milliseconds to wait for a connection to the remote HTTP server, before timing out (and possibly retrying on a separate connection). This is 5s by default.
protocol-version String No 1.1 The HTTP protocol version to use. May be either “1.0”, “1.1” or “2.0”.

The default-request-timeout-ms can be overridden on a per-template basis.

Server Endpoints

A server endpoint is configured with the following basic elements:

{
    "name": "selfcare",
    "service-type": "REST",
    "router": "selfcare-router",
    "interface": "0.0.0.0",
    "port": 8080
}

To configure a server, the following configuration options are available:

Field Type Required? Default Description
name String Yes - The name to know the server as. This forms the endpoint name for the JSLEE message bus, and must be unique within the JSLEE service. This is the name messages that are received by this server will use when sending requests to other JSLEE services.
service-type String Yes - Either the word SOAP or REST (in capitals). Defines whether the HTTP connection is expected to receive SOAP or REST requests. SOAP based connections require some additional work by the service, so must be explicitly configured.
router String Yes - Which router configuration (defined as part of this JSLEE service) this HTTP server must used when determining the route for incoming messages.
interface String Yes - The IP address of the interface to listen on. To listen on the loopback, use 127.0.0.1, and to listen on all interfaces, use 0.0.0.0.
port Number Yes - The TCP port to run the HTTP server on.
web-server-options Object No - Additional options for the server (both TCP and HTTP oriented).

Web Server Options

Additional server options can be provided using the web-server-options configuration object. This includes the Vert.X TCP configuration, more information of which can be found in the TCP options.

Note that a HTTP server endpoint will automatically use HTTP 2.0 if clients connect as HTTP 2.0.

If used, it is recommended that HTTP 100 (Continue) messages are configured to be automatically responded to. Do this with the configuration:

{
  "handle100ContinueAutomatically": true
}

If no web-server-options are given, this is the default. Note that the linked TCP options are documented in the a-b format, however due to the method in which the web-server-options are parsed, these options must be given to the HTTP web server using the default Vert.X web server options format which is camelCase.