Getting Started with the ConversionQA REST API

ConversionQA provides a REST API in addition to its Java API. This API allows it to be accessed from a wide range of services.

Starting the Service

To start the REST service, you will simply need to call the ConversionQA JAR from the command-line with an added parameter:

CODE

$ java -jar deltaxml-conversion-qa-1.0.0.jar start-rest-server

DeltaXML ConversionQA 1.0.0
Released 2023-09-28
Copyright (c) 2023 Deltaman Group Ltd. All rights reserved.

Oct 13, 2023 10:25:31 AM org.glassfish.grizzly.http.server.NetworkListener start
INFO: Started listener bound to [0.0.0.0:8080]
Oct 13, 2023 10:25:31 AM org.glassfish.grizzly.http.server.HttpServer start
INFO: [HttpServer] Started.
ConversionQA REST service started, navigate to: http://0.0.0.0:8080/api/conversionqa/v1/check
Control-C to stop it...

Server Configuration

See this page for configuration options for the REST server: ConversionQA REST server configuration

How to Specify a Conversion Check Request

Method: POST /check

For information on the different protocols that can be used for specifying inputs/outputs see: REST I/O Types

For information on how to start a Job see: How to Start a ConversionQA Job

Example Requests

multipart/form-data

CODE

POST /api/conversion-checker/v1/check HTTP/1.1
Content-Type: multipart/form-data; boundary=boundary-id
Content-Length: number_of_bytes_in_entire_request_body

--boundary-id
Content-Disposition: form-data; name="inputA"; filename="inputA.xml"
Content-Type: application/xml

(data)

--boundary-id
Content-Disposition: form-data; name="dxFormatA"
xml

... XML  ...
--boundary-id
Content-Disposition: file; name="inputB"; filename="inputB.zip"
Content-Type: application/zip

(data)
--boundary-id
Content-Disposition: form-data; name="dxFormatB"
ditamap

--boundary-id
Content-Disposition: form-data; name="dxMasterFileB"
inputB/map.ditamap

--boundary-id

XML Structured Request

XML

<checkConversion>
    <inputA type="file">
        <path>inputA.xml</path>
        <dxFormat>xml</dxFormat>
    </inputA>
    <inputB protocol="http">
        <uri>inputB.zip</uri>
        <dxFormat>ditamap</dxFormat>
        <dxMasterFile>inputB/map.ditamap</dxMasterFile>
    </inputB>
</checkConversion>

JSON Structured Request

JSON

{
  "inputA": {
    "type": "file",
    "path": "inputA.xml",
    "dxFormat": "xml"
  },
  "inputB": { 
    "protocol": "http",
    "uri": "https://example.com/inputB.zip",
    "dxFormat": "ditamap",
    "dxMasterFile": "inputB/map.ditamap"
  }
}

Request Model

Form Parameters

Parameter	Description and example usage
inputA (required)	Input A Can be specified in either a file path, a HTTP URI, or raw XML
dxFormatA (required)	Can be either `xml`, `ditamap`, or `docx`
dxMasterFileA	When using `ditamap` inputs, this needs to be set to the name of the DITA Map file within the zip, e.g. "main.ditamap"
inputB (required)	Input B Can be specified in either a file path, a HTTP URI, or raw XML
dxFormatB (required)	Can be either `xml`, `ditamap`, or `docx`
dxMasterFileB	When using `ditamap` inputs, this needs to be set to the name of the DITA Map file within the zip, e.g. "main.ditamap"
catalog	File path or HTTP URI pointing to catalog file(s) used during the conversion check.
async	Whether async comparison is used. Default value if not specified: false
output	An optional file path to write the output to when using async. E.g. "/Users/exampleUser/Documents/test.xml"
callback	Callback URL called after comparison is complete. Note : only used with asynchronous comparisons. See this page.

XML / JSON Structured Requests

Object		Description
inputA (required)	dxFormat (required)	Input A to the comparison. See this page for the various I/O types available and the extra options they have.
inputA (required)	dxMasterFile	Optional parameter when using `ditamap` comparison.
inputB (required)	dxFormat (required)	Input B to the comparison. See this page for the various I/O types available and the extra options they have.
inputB (required)	dxMasterFile	Optional parameter when using `ditamap` comparison.
catalog		File path or HTTP URI pointing to catalog file(s). See this page for the various I/O types available and the extra options they have.
async	output	Specification of where the comparison result will be written. See this page for the various I/O types available and the extra options they have.
async	callback	URL that will be polled after the comparison is complete. See Callback for more information.

Response

ConversionQA sets a HTTP header isContentEqual to either true or false to indicate whether the conversion check was successful or not.

The body of the response will either be the Change Report (default - ‘synchronous' check), information on the created Job when using an 'asynchronous’ check, or an error response . For more information on setting up Jobs see this guide.

How to Check Server Status

Method: GET /status

Optional query parameter:

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

Example Response

XML

<serverStatus>
    <apiName>DeltaXML ConversionQA REST</apiName>
    <released>20230817.0</released>
    <version>1.0.0</version>
    <serverStarted>2023-09-19T15:53:56+0100</serverStarted>
</serverStatus>

Testing with Postman

Import our Postman collection for examples of how to make requests to the server, see this page for more details: Testing ConversionQA REST with Postman

Shutdown

The REST server can be shutdown using following options:

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

In the above cases, the REST server will check for any running check operations before initiating the shutdown. ConversionQA REST will shut itself down after completing all the running operations. At the same time, the server will not accept any new check operation request.

Shutdown endpoint

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

Response

XML

<shutdownInfo>
    <initiateTime>2023-01-24T15:53:42.835+0000</initiateTime>
    <runningComparisons>0</runningComparisons>
    <info>ConversionQA REST Server shut down initiated. It will be completed after finishing the running comparisons.</info>
</shutdownInfo>

Shutdown due to license server

This applies for customers with Concurrent Operations licenses

The REST server will intermittently check for a ‘heartbeat’ from the license server. If the license server goes down for any reason, e.g. license expiry, network outage, etc, the ‘heartbeat’ will be lost. The REST server will attempt to reconnect, but if it cannot it will initiate a shutdown.