Starting your REST server

Introduction

The HTML Compare REST service allows you to invoke HTML comparisons from a wide range of programming languages and systems.

Installation

The JARs for REST are included in the HTML Compare release. They have a suffix indicating the major.minor.version, here shown as x.y.z:

deltaxml-html-compare-rest-x.y.z.jar which needs to be kept in the same directory as an HTML Compare release.
deltaxml-html-compare-rest-client-x.y.z.jar which can work independently and be placed anywhere

A license file is required to enable the REST service. The file should be called deltaxml-html-compare-rest.lic and should contain a license feature for ‘html_compare_rest’. The file should also be placed into the HTML Compare install directory together with existing jar and license files.

Starting the Service

To start the REST service, you will simply need to call the HTML Compare REST-JAR from the command-line with the following command:

Note

To use the following command-line samples, replace x.y.z with the major.minor.patch version number of your release e.g. deltaxml-html-compare-rest-1.0.0.jar

CODE

java -jar deltaxml-html-compare-rest-1.0.0.jar

HTML Compare REST service started, navigate to: http://0.0.0.0:8080/api/html-compare/v1/compare
Control-C to stop it...

Host

The default host name of the server is http://localhost:8080

To change this, set the host system property when starting the rest server:

CODE

java -Dhost=http://localhost:1234 -jar deltaxml-html-compare-rest-1.0.0.jar

This cannot be used with Fixed Host REST licenses. If you need to change the port, contact DeltaXML.

How to Check Server Status

Method: GET /status

Optional query parameter:

licenseCheck - boolean (true/false) whether to include license information.

Example Response

CODE

<serverStatus>
    <apiName>deltaxml-html-compare-rest</apiName>
    <released>20240523.0</released>
    <version>1.0.0</version>
    <serverStarted>2024-08-15T08:23:13+0100</serverStarted>
    <port>8080</port>
</serverStatus>

Shutdown

The rest server can be shutdown using the following options:

Using Control-C from the terminal to end the process
System wide shutdown
Using REST Server /shutdown endpoint

In the above cases, the REST server will check for any running check operations before initiating the shutdown. HTML Compare REST will shut itself down after completing all running comparisons and not accept any new comparisons during this process

REST Server Shutdown endpoint

Calling POST /shutdown allows you to remotely stop the REST server:

Response

CODE

<shutdownInfo>
    <initiateTime>1723712119518</initiateTime>
    <runningComparisons>0</runningComparisons>
    <info>REST Server shut down initiated. It will be completed after finishing the running comparisons.</info>
</shutdownInfo>

Shutdown due to license server

A license server can go down for several reasons including:

Intentional license server shutdown
License expiry
System shutdown
Power outage

The REST server is constantly checking for license server heartbeat and it will be lost if license server goes down. The REST Server will try to reconnect to a license server 2 times after some defined interval. The REST Server will initiate the graceful shutdown if it fails to reconnect.