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:
- The web services templating engine uses FreeMarker version 2.3.28. All templates must conform to this version of 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 define how the JSLEE service will connect to HTTP servers.server
endpoints define how the JSLEE will operate HTTP servers, for clients to connect to.
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
.