DocBook Compare REST Server Installation and Setup Guide

Introduction

This guide is designed for users of the DocBook Compare REST API. It provides help for the installation and initial setup of the HTTP server and wrapper component that provides the DocBook Compare REST API. The DocBook Compare REST service allows you to invoke DocBook comparisons from a wide range of programming languages and systems.

Installation

The JARs for REST are included in the DocBook Compare (Java) release. They have a suffix indicating the major.minor.patch version, here shown as 9.0.0:

deltaxml-docbook-rest-9.0.0.jar which needs to be kept in the same directory as an DocBook Compare release.
deltaxml-docbook-rest-client-9.0.0.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-docbook-rest.lic and should contain a license feature for docbook_rest. The file should also be placed into the DocBook Compare install directory together with existing jar and license files.

Starting and Stopping the Service

To start the REST service use the following command (adjust heap and stack sizes as needed or to suit the target system) from the install directory. If all is well some lines of debug and information messages will appear as indicated below.

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-docbook-rest-9.0.0.jar

CODE

$ java -jar deltaxml-docbook-rest-x.y.z.jar
Apr 12, 2018 10:44:40 AM org.glassfish.grizzly.http.server.NetworkListener start
INFO: Started listener bound to [0.0.0.0:8080]
Apr 12, 2018 10:44:40 AM org.glassfish.grizzly.http.server.HttpServer start
INFO: [HttpServer] Started.
DocBook Compare REST service started, navigate to: http://0.0.0.0:8080/api/docbook-compare/v1/compare
Control-C to stop it...

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

Default Configuration

To specify a default configuration used if you don’t specify configuration in your request, use a deltaxmlConfig.xml file (see more details here) and use the property com.deltaxml.docbook.rest.defaultConfiguration to point to a valid config file, e.g. :

XML

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE deltaxmlConfig
        SYSTEM "deltaxml-config.dtd">
<deltaxmlConfig>
    <configProperty name="com.deltaxml.docbook.rest.defaultConfiguration" value="/Users/test/topic-configuration.xml"/>
    <configSearchPath>
        <search path="${install.dir}${file.separator}deltaxmlConfig.xml"/>
        <search path="${user.home}${file.separator}deltaxmlConfig.xml"/>
        <search path="${user.dir}${file.separator}deltaxmlConfig.xml"/>
    </configSearchPath>
</deltaxmlConfig>

You can also place a file named default-configuration.xml in the same directory as the REST JAR and it will be picked up if you don't use the deltaxmlConfig.xml approach.

Default Catalog

You can use the standard xml.catalog.files property (either as a Java system property or through the deltaxmlConfig.xml file) to specify the catalog files to be used so you don't have to specify catalog on each request.

HTTPS

To use HTTPS you will need to generate an SSL Certificate that can be verified with a Certificate Authority's keys that are included in the JDK. We have internally tested and recommend using Let's Encrypt (https://letsencrypt.org), using this guide to import a Let's Encrypt certificate into a Java KeyStore - https://community.letsencrypt.org/t/tutorial-java-keystores-jks-with-lets-encrypt/34754/10
What the guide doesn't tell you is you should also specify a password for the key itself (i.e. using the -destkeypass parameter)
Note: You will need to use the same password for the KeyStore and the Key itself.

When starting up the REST service, use the Java system properties keystore and keypass to specify the location of the KeyStore, and the password for the KeyStore/Key, for example:

CODE

java -jar deltaxml-docbook-rest-x.y.z.jar -Dkeystore=/Users/exampleUser/rest/keystore.jks -Dkeypass=password

If using Postman to test the API - if you didn't use Let's Encrypt and chose to use a self-signed certificate, you will need to disable "SSL Certificate Verification" in the Postman Settings.

Using the Service

Postman

The Postman API development and testing app provides a simple way to test the DocBook Compare REST API. We provide a Postman Collection to help get you started with the REST API, details on this are included in the Testing Using Postman section of the REST User Guide.

Command-line invocation

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