Running a REST Service Application in the Direct REST Mode

Before the implementation of Direct REST functionality, access to REST applications was available using only IIS. Client applications would make HTTP/1.1 REST requests to IIS, and then IIS would communicate with the Jade REST application to serve responses to these requests. The communication between the IIS and the Jade REST application was performed by the Internet Server Application Programming Interface (ISAPI) extension Dynamic Link Library (DLL) called jadehttp.dll. This DLL implemented a proprietary Jade protocol between IIS and the REST applications.

The Direct REST functionality adds support for the HTTP/1.1 communication protocol to REST applications. This means that Jade REST applications, when run in the Direct REST mode, no longer require IIS to enable communication with other HTTP‑compliant applications (for example, REST clients, web browsers, reverse proxies, web servers, or TLS termination servers). This allows a greater degree of freedom for the deployment of Jade REST applications and it also reduces the system requirements for the development of REST applications. See also the Direct REST Reference Architecture White Paper, for suggestions and example deployment configurations that could be used with Jade Direct REST services.

The general steps to define a REST Service application are specified in "Defining a REST Service Application", earlier in this chapter.

The only functionality not provided by the JadeRestService class when REST applications are run in the Direct REST mode are the three methods related to the use of the legacy IIS virtual directory feature (that is, createVirtualDirectoryFile, deleteVirtualDirectoryFile, and isVDFilePresent). If these methods are called in a Direct REST application, exception 1068 (Feature not available in this release) is raised.

As the use of the virtual directory (specified in the Virtual Directory text box on the Web Options sheet of the Define Application dialog) is normally reserved for serving files to web applications and REST applications are traditionally used to provide data access, the Virtual Directory text box on the Web Options sheet of the Define Application dialog is not required functionality for REST applications; that is, it is optional.

As the use of the virtual directory (specified in the Virtual Directory text box on the Web Options sheet of the Define Application dialog) is normally reserved for serving files to web applications and REST applications are traditionally used to provide data access. It is not required functionality for Direct REST web applications; that is, it is optional.

In the following image, the highlighted entry is for a REST application called RestServer. There is also another REST application called RestServerNonGui, but these applications could also be called Tom, Dick, or Harry.

To run a REST Services application

If you have the following setting of the DirectRest parameter in the [WebOptions] section of the Jade initialization file, all Rest Services and Rest Services, Non-Gui applications on your node run in Direct mode.
```
[WebOptions]
DirectRest=true
```
If you have the following (default) setting of the DirectRest parameter in the [WebOptions] section of the Jade initialization file, all Rest Services and Rest Services, Non-Gui applications on your node run in the legacy IIS mode.
```
[WebOptions]
DirectRest=false
```
If your node has a Rest Services application called YellowRulesTheRest and the following DirectRest parameter settings, the application called YellowRulesTheRest runs in Direct REST mode but all other Rest Services and Rest Services, Non-Gui applications on that node run in legacy IIS mode.
```
[WebOptions]
DirectRest=false
YellowRulesTheRest_DirectRest=true
```

In addition to the DirectRest parameter, the [WebOptions] section of the Jade initialization file also provides the parameters listed in the following table.

Parameter	Specifies...
KeepAliveTimeout	The maximum time a connection will be held open after a response has been sent.
LogHttpMessages	Whether HTTP messages are logged. If logging of HTTP messages is enabled, they are also displayed in the console of GUI REST applications.
MaxRequestLength	Maximum length (in bytes) of HTTP requests for REST applications running in Direct REST mode.
MinimumReadDataRate	Minimum rate allowed for incoming data (defined in kilobits per second).
QueueDepthMax	Maximum size of the REST request queue.

In addition, you can use the JadeRestService class addResponseHeaderField method to add HTTP header fields for an individual Direct REST response. When running in Direct mode, Jade REST applications continue to support the JadeRestService class reply method extension point. In addition, the JadeRestService class extension replyBinary method is called when a response with a binary payload has been generated. See also "Sending Binary Payloads in Direct REST Responses", elsewhere in this chapter.

Running Existing REST Applications in Direct Mode

The majority of pre‑existing REST applications should be able to run in the legacy or Direct modes, without the need to change any application code.

To run an existing Jade REST application in Direct REST mode, simply:

Add the DirectRest parameter with a value of true to the [WebOptions] section of the Jade initialization file.
Disable IIS.

This step is not required if the REST application is configured to talk on any port other than the standard HTTP and HTTPS ports of 80 and 443.

Any GET methods exposed by the REST application can then be accessed by a local web browser.

The following example accesses the getTestObject method on a REST application (of any name) that is configured to serve requests on port 12345.

The full HTTP request, which will obtain the same response (if sent to the correct port on the machine hosting the REST server application) is:

GET /TestObject HTTP/1.1<CrLf><CrLf>

In this request, <CrLf> is a placeholder for the non‑printable ASCII character sequence 0x0D 0x0A.

2022.0.05 and higher