Runtime Configuration for REST and SOAP¶

Runtime Configuration for REST and SOAP

Introduction¶

FWD supports both the conversion and runtime for 4GL web services. For details on how to convert REST and SOAP services, please see Converting REST and SOAP.

FWD will expose the REST and SOAP endpoint URLs, and once the target is found, it will delegate the call to an AppServer Agent. See Configuring Legacy Appservers how to setup the runtime for these.

The runtime support for SOAP and REST requires a FWD process account to be configured. This account can be shared between these configurations, as it will be used solely for establishing a FWD context so that it can connect to the AppServer and delegate the calls.

A process account exists in the directory under the /security/accounts/processes/ node. Its simple structure is this:

          <node class="process" name="<process-name>">
            <node-attribute name="enabled" value="TRUE"/>
            <node-attribute name="description" value="This is a sample process account"/>
            <node-attribute name="master" value="FALSE"/>
            <node-attribute name="server" value="FALSE"/>
            <node-attribute name="alias" value="<certificate-alias>"/>
          </node>

Once the FWD process account(s) have been added, a certificate must be loaded in the FWD Server's directory, for each added account. If you are using self-signed certificates and these were previously generated with FWD's Cryptography Setup Helper tool, you can use the same tool to generate the certificates and private keys for the newly added accounts (or, you can (re)generate self-signed certificates for all accounts, using the same tool). Otherwise, you must configure each process account with a certificate, following the Certificates instructions.

In the next sections, this chapter will describe how to configure the runtime such that properly converted REST, REST via WebHandler and SOAP services will execute in FWD.

REST¶

Service registration is being performed at FWD server startup, which loads and maps all the programs annotated as REST services.

The implicit basepath is /rest, and the implicit timeout is 10 seconds (which can be set to 0 to disable it). This timeout is inherited from the appserver's timeout.

The directory configuration is read from a rest/ node, which must exist under the server/default or server/<server-ID>. The values which need to be configured are:

rest/enabled, to explicitly enable the REST runtime support. Defaults to false.
rest/basepath, to specify the basepath. Defaults to /rest.
rest/alias, a process certificate alias associated with the worker's process account which will process the SOAP requests; this is the caller's process which will delegate the call to an Appserver agent process for execution. In FWD, this alias is needed to authenticate the worker thread with the FWD server, and to obtain a security context.
rest/keyStore, the key store with the certificate to authenticate this process. If is missing, the store will be built from the directory.
rest/storePassword, the store password, only if rest/keyStore is set.
rest/entryPassword, the key entry password, only if rest/keyStore is set.
rest/poolSize - the pool size of workers. Defaults to 10.
rest/appserver - the name of the appserver handling the requests. In FWD, this must be one of the entries in /server/default/appservers/ or /server/<id>/appservers. In OpenEdge configuration this will be specified as appservername.ROOT.REST.

Each queue of REST workers is ordered by the number of pending tasks to be executed - for each incoming request, the worker with the smallest number of pending tasks will be chosen.

The full directory node will look like:

        <node class="container" name="rest">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="string" name="basepath">
            <node-attribute name="value" value="rest/"/>
          </node>
          <node class="string" name="alias">
            <node-attribute name="value" value="<process-id>"/>
          </node>
          <node class="string" name="keyStore">
            <node-attribute name="value" value="/path/to/process/keystore"/>
          </node>
          <node class="string" name="storePassword">
            <node-attribute name="value" value="<password>"/>
          </node>
          <node class="string" name="entryPassword">
            <node-attribute name="value" value="<password>"/>
          </node>
          <node class="integer" name="poolSize">
            <node-attribute name="value" value="10"/>
          </node>
          <node class="string" name="appserver">
            <node-attribute name="value" value="<appserver-name>"/>
          </node>
        </node>

and the minimal configuration is:

        <node class="container" name="rest">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="string" name="alias">
            <node-attribute name="value" value="<process-id>"/>
          </node>
          <node class="string" name="appserver">
            <node-attribute name="value" value="<appserver-name>"/>
          </node>
        </node>

In the above examples, the following values must be specified and/or configured:

<appserver-name> - the name of the AppServer which will handle the requests. See Configuring Legacy Appservers
<process-id> - the name of a Process FWD account, which will be used to authenticate the REST handler threads and allow them to connect to the AppServer (running in the same FWD server). See
/path/to/process/keystore - if this is missing, it means the keystore is configured in the FWD directory. Otherwise, provide a full path to the process keystore with its private key.
<password> - only if an explicit keystore is used, must be the password for the key store or store entry, in clear-text.

To access a REST endpoint, use the secure port for the server followed by the service path, like https://localhost:7443/rest/path/to/service, where path/to/service is an explicit path for a certain REST service.

REST via WebHandler¶

Service registration is being performed at FWD server startup, which loads and maps all the legacy classes annotated as web services.

The implicit basepath is /web, and the implicit timeout is 10 seconds (which can be set to 0 to disable it). This timeout is inherited from the appserver's timeout.

The directory configuration is read from a WebHandler/ node, which must exist under the server/default or server/<server-ID>. The values which need to be configured are:

WebHandler/enabled, to explicitly enable the web handler runtime support. Defaults to false.
WebHandler/basepath, to specify the basepath. Defaults to /web. This can be found in an existing OpenEdge configuration in an entry like wsRoot=http://host:port/static/webspeed and the basepath in this example would be /static/webspeed.
WebHandler/alias, a process certificate alias associated with the worker's process account which will process the web requests; this is the caller's process which will delegate the call to an Appserver agent process for execution. In FWD, this alias is needed to authenticate the worker thread with the FWD server, and to obtain a security context.
WebHandler/keyStore, the key store with the certificate to authenticate this process. If is missing, the store will be built from the directory.
WebHandler/storePassword, the store password, only if WebHandler/keyStore is set.
WebHandler/entryPassword, the key entry password, only if WebHandler/keyStore is set.
WebHandler/poolSize - the pool size of workers. Defaults to 10.
WebHandler/appserver - the name of the appserver handling the requests. In FWD, this must be one of the entries in /server/default/appservers/ or /server/<id>/appservers. In OpenEdge configuration this will be specified as appservername.ROOT.WEB.

Each queue of web service workers is ordered by the number of pending tasks to be executed - for each incoming request, the worker with the smallest number of pending tasks will be chosen.

The full directory node will look like:

        <node class="container" name="WebHandler">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="string" name="basepath">
            <node-attribute name="value" value="web/"/>
          </node>
          <node class="string" name="alias">
            <node-attribute name="value" value="<process-id>"/>
          </node>
          <node class="string" name="keyStore">
            <node-attribute name="value" value="/path/to/process/keystore"/>
          </node>
          <node class="string" name="storePassword">
            <node-attribute name="value" value="<password>"/>
          </node>
          <node class="string" name="entryPassword">
            <node-attribute name="value" value="<password>"/>
          </node>
          <node class="integer" name="poolSize">
            <node-attribute name="value" value="10"/>
          </node>
          <node class="string" name="appserver">
            <node-attribute name="value" value="<appserver-name>"/>
          </node>
        </node>

and the minimal configuration is:

        <node class="container" name="WebHandler">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="string" name="alias">
            <node-attribute name="value" value="<process-id>"/>
          </node>
          <node class="string" name="appserver">
            <node-attribute name="value" value="<appserver-name>"/>
          </node>
        </node>

In the above examples, the following values must be specified and/or configured:

<appserver-name> - the name of the AppServer which will handle the requests. See Configuring Legacy Appservers
<process-id> - the name of a Process FWD account, which will be used to authenticate the web service handler threads and allow them to connect to the AppServer (running in the same FWD server).
/path/to/process/keystore - if this is missing, it means the keystore is configured in the FWD directory. Otherwise, provide a full path to the process keystore with its private key.
<password> - only if an explicit keystore is used, must be the password for the key store or store entry, in clear-text.

To access a web service endpoint, use the secure port for the server followed by the service path, like https://localhost:7443/web/path/to/service, where path/to/service is an explicit path for a certain web service.

SOAP / Web Services Adapter (WSA)¶

Service registration is being performed at FWD server startup, which loads and maps all the programs annotated as SOAP services.

The implicit basepath is /ws, and the implicit timeout is 10 seconds (which can be set to 0 to disable it). This timeout is inherited from the appserver's timeout.

The directory configuration is read from a soap/ node, which must exist under the server/default or server/<server-ID>. The values which need to be configured are:

soap/enabled, to explicitly enable the SOAP runtime support. Defaults to false.
soap/basepath, to specify the basepath. Defaults to /ws. This can be found in an existing OpenEdge configuration in an entry like wsaUrl=http://host:port/soap and the basepath in this example would be /soap.
soap/alias, a process certificate alias associated with the worker's process account which will process the SOAP requests; this is the caller's process which will delegate the call to an Appserver agent process for execution. In FWD, this alias is needed to authenticate the worker thread with the FWD server, and to obtain a security context.
soap/keyStore, the key store with the certificate to authenticate this process. If is missing, the store will be built from the directory.
soap/storePassword, the store password, only if soap/keyStore is set.
soap/entryPassword, the key entry password, only if soap/keyStore is set.
soap/poolSize - the pool size of workers. Defaults to 10.
soap/appserver - the name of the appserver handling the requests.In FWD, this must be one of the entries in /server/default/appservers/ or /server/<id>/appservers. In OpenEdge configuration this will be specified as appservername.ROOT.SOAP.

Each queue of SOAP workers is ordered by the number of pending tasks to be executed - for each incoming request, the worker with the smallest number of pending tasks will be chosen.

The full directory node will look like:

        <node class="container" name="soap">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="string" name="basepath">
            <node-attribute name="value" value="ws/"/>
          </node>
          <node class="string" name="alias">
            <node-attribute name="value" value="<process-id>"/>
          </node>
          <node class="string" name="keyStore">
            <node-attribute name="value" value="/path/to/process/keystore"/>
          </node>
          <node class="string" name="storePassword">
            <node-attribute name="value" value="<password>"/>
          </node>
          <node class="string" name="entryPassword">
            <node-attribute name="value" value="<password>"/>
          </node>
          <node class="integer" name="poolSize">
            <node-attribute name="value" value="10"/>
          </node>
          <node class="string" name="appserver">
            <node-attribute name="value" value="<appserver-name>"/>
          </node>
        </node>

and the minimal configuration is:

        <node class="container" name="soap">
          <node class="boolean" name="enabled">
            <node-attribute name="value" value="TRUE"/>
          </node>
          <node class="string" name="alias">
            <node-attribute name="value" value="<process-id>"/>
          </node>
          <node class="string" name="appserver">
            <node-attribute name="value" value="<appserver-name>"/>
          </node>
        </node>

In the above examples, the following values must be specified and/or configured:

<appserver-name> - the name of the AppServer which will handle the requests. See Configuring Legacy Appservers
<process-id> - the name of a Process FWD account, which will be used to authenticate the SOAP handler threads and allow them to connect to the AppServer (running in the same FWD server).
/path/to/process/keystore - if this is missing, it means the keystore is configured in the FWD directory. Otherwise, provide a full path to the process keystore with its private key.
<password> - only if an explicit keystore is used, must be the password for the key store or store entry, in clear-text.

To access a SOAP endpoint, use the secure port for the server followed by the base path, like https://localhost:7443/ws.

The WSDL can be accessed using the base path following the service name, like https://localhost:7443/ws/ServiceName/wsdl.

Project

General

Profile

FWD

Wiki

Runtime Configuration for REST and SOAP¶

Introduction¶

REST¶

REST via WebHandler¶

SOAP / Web Services Adapter (WSA)¶