Skip to main content
Skip table of contents

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.

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.

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. 

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.