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:
$ 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
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
<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
{
"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 |
dxMasterFileA | When using |
inputB (required) | Input B Can be specified in either a file path, a HTTP URI, or raw XML |
dxFormatB (required) | Can be either |
dxMasterFileB | When using |
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 | |
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 | |
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
<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
<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.