Installing and Setting Up DeltaNova REST On-Premise

This section describes how to install and set up the HTTP server and wrapper component that provides the DeltaNova REST API, enabling you to invoke any DeltaNova capability from a wide range of programming languages and systems.

Prerequisites

A license file is required to enable the REST service. The file is called deltanova-rest.lic and contains a license feature for deltanova_rest.
The license file must be placed in the DeltaNova install directory, together with the existing JAR and license files.

Context

The JARs for REST are included in the DeltaNova (Java) release. They have a suffix indicating the year.major.minor.patch version, shown in this topic as year.x.y.z. Where a command line sample uses year.x.y.z, replace it with the version number of your release, such as deltanova-rest-year.x.y.z.jar.

Steps

Place deltanova-rest-year.x.y.z.jar in the same directory as a DeltaNova release.
Place deltanova-rest-client-year.x.y.z.jar anywhere; it can work independently.

To start the REST service, run the following command from the install directory. Adjust heap and stack sizes as needed to suit the target system.

java -Xmx4g -Xss20m -jar deltanova-rest-year.x.y.z.jar

Step result: If the service starts successfully, debug and information messages appear as follows:

Loading Pipelines...
Loaded pipeline: schema
Loaded pipeline: doc-xhtml
Loaded pipeline: doc-delta
Loaded pipeline: diffreport-sbs
Loaded pipeline: doc-diffreport
Loaded pipeline: doc-diffreport-sbs
Loaded pipeline: delta
Loaded pipeline: diffreport
Loaded pipeline: data-delta
Loaded pipeline: raw
Pipelines Loading Completed.
XML Compare REST service started.
Navigate to: http://0.0.0.0:8080/api/pipelines
Control-C to stop it...

Alternatively run the command java -DignoreSamplesPipelines=true -jar deltanova-rest-2026.1.0.0.jar to only load custom pipelines. See Pipelines and Discovery for more detail on Pipelines.

To stop the service, use Control-C as indicated, or an appropriate operating system command or tool such as kill.

Result

The DeltaNova REST service is installed and can be started and stopped from the install directory.

Postrequisites

To secure the service, configure HTTPS. See Configuring HTTPS for DeltaNova REST.
To start using the service, see Using the DeltaNova REST Service.

Configuring HTTPS for DeltaNova REST

Short description: Generate an SSL certificate, package it in a Java keystore (JKS), and apply the keystore to the DeltaNova REST service to enable HTTPS.

Prerequisites

To use HTTPS, you need to generate an SSL certificate that can be verified with a Certificate Authority's keys included in the JDK. Let's Encrypt has been tested internally.
For viewing the contents of a keystore, you can use KeyStore Explorer. Once you have a keystore (a JKS file), open it in KeyStore Explorer to see its contents.

Warning: If you are using Postman to test the API and you chose a self-signed certificate rather than Let's Encrypt, you must disable SSL Certificate Verification in the Postman Settings.

Option 1: Generate a Self-signed Certificate

Run the following command:

keytool -genkeypair -alias myssl -keyalg RSA -keysize 2048 -validity 365 -keystore myssl.jks -storepass changeme

Fill in the questions when prompted (name, organizational unit, organization, locality, state or province, and two-letter country code).

Step result: You have a JKS file that you can use against your JAR file.

(Optional) Export the certificate if you want to use it elsewhere:

keytool -export -alias myssl -file myssl.cer -keystore myssl.jks -storepass changeme

Verify the keystore entries:
```
keytool -list -v -keystore myssl.jks -storepass <password>
```
Step result: The command lists one entry in the keystore.

Alternatively, open the JKS file in KeyStore Explorer to inspect the entry:

Option 2: Use a Let's Encrypt or Official Certificate

Note: This assumes you have successfully obtained the Let's Encrypt certificate files, consisting of cert.pem, chain.pem, fullchain.pem, and privkey.pem. In the examples below, replace the example domain with your own domain, and make sure you change and secure the password you use.

Add all .pem files to a PKCS 12 archive. It is not possible to import multiple public and private .pem certificates directly into a keystore, so this must be done first. Use the OpenSSL tool, for example:
```
openssl pkcs12 -export -in cert.pem -inkey privkey.pem -out deltaxml.com.p12 -name http://deltaxml.com -CAfile fullchain.pem -caname "Let's Encrypt Authority X3" -password pass:changethis
```

Import the certificates into a keystore (.jks) file:

keytool -importkeystore -deststorepass changethis -destkeypass changethis -deststoretype pkcs12 -srckeystore deltaxml.com.p12 -srcstoretype PKCS12 -srcstorepass changethis -destkeystore deltaxmlcom.jks -alias http://deltaxml.com

Apply the Keystore to DeltaNova

Warning: The following command uses naming conventions and passwords from the examples above; don't forget to change them.

Assuming you've successfully created a JKS file using one of the methods above, apply it to DeltaNova as follows:
```
java -Dkeystore=.\deltaxmlcom.jks -Dkeypass=changethis -jar deltanova-rest-year.x.y.z.jar
```

Result

Server side: The service starts with messages confirming the HTTP listener is bound and the REST service has started, with a https:// URL to navigate to, for example https://0.0.0.0:8080/api/compare/pipelines/delta.
Client side: Navigating to the service URL in a browser shows the pipelines XML response, and the certificate viewer shows the certificate details for your domain.
Postman: If you are using Postman with a self-signed certificate, don't forget to switch off SSL Certificate Validation.

Using the DeltaNova REST Service

Explore and invoke the DeltaNova REST API using Postman, a web browser, or the sample command-line driver.

Postman

The Postman API development and testing app provides a simple way to test the DeltaNova REST API. A Postman Collection is provided to help get you started with the REST API; details are included in the Testing Using Postman section of the REST User Guide.

Browser-based discovery

Alternatively, the service supports HATEOAS principles and can be explored using a web browser. Start at:

http://localhost:8080/api/compare/xml/pipelines/

Substitute the scheme (http or https), hostname, and port depending on your setup.

Pipeline discovery

The final part of the URL above is pipelines. Details on how pipelines are discovered and used for XML Comparison, and the other capabilities, can be found in the Pipelines and Discovery section of the REST User Guide.

Command-line invocation

A sample command-line driver that exploits the REST API is also provided. For more detail, see Testing using Sample Command Line Driver.