Map Topicset Comparison Example

Synchronous Comparison Example

Comparison Model

When specifying a comparison using XML or JSON structured requests, these are the various available objects:

Object

Description

inputA

(required)

Input A to the comparison.

See this page for the various I/O types available.

inputB

(required)

Input B to the comparison.

See this page for the various I/O types available.

configuration

Configuration to the comparison

See this page for the various I/O types available.

catalog

File path or HTTP URI pointing to catalog file(s).

See this page for the various I/O types available.

async

output

Specification of where the comparison result will be written.

See this page for the various I/O types available.

callback

URL that will be polled after the comparison is complete.

See Callbacks in Async for more information.

Here is a simple synchronous example (asynchronous comparison is detailed in more detail on this page):

Request (XML)

XML

<comparison>
    <inputA type="file">
        <path>/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/inA.zip</path>
        <masterMap>inA/inA.ditamap</masterMap>
    </inputA>
    <inputB type="file">
        <path>/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/inB.zip</path>
        <masterMap>inB/inB.ditamap</masterMap>
    </inputB>
    <configuration type="file">
         <path>/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/config.xml</path>
    </configuration>
</comparison>

Request (JSON)

JSON

{
  "inputA": {
    "type": "file",
    "path": "/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/inA.zip",
    "masterMap": "inA/inA.ditamap"
  },
  "inputB": {
    "type": "file",
    "path": "/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/inB.zip",
    "masterMap": "inB/inB.ditamap"
  },
  "configuration": {
    "type": "file",
    "path": "/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/config.xml"
  }
}

The response below indicates the comparison result, in this case a zip file that once unzipped describes the changes between the inputs specified in the request.

Note that we only accept ZIP files with a .zip extension as inputs to the map topicset comparison

Response

The response is a zip file that can be opened and output can typically be found under the _b-0-file- directory.

Screenshot 2024-05-07 at 12.30.28 pm.png

Form Input

In addition to requests in structured XML or JSON format, multipart/form-data can also be used.

The following table describes the parts that can make up the form-data:

Parameter	Description and example usage
inputA (required)	Input A Can be specified in either a file path, a HTTP URI, or raw zip input
masterMapA (required)	Relative path to the unzipped master map for input A
inputB (required)	Input A Can be specified in either a file path, a HTTP URI, or raw zip input
masterMapB (required)	Relative path to the unzipped master map for input B
catalog	File path or HTTP URI pointing to catalog file(s).
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.

For example:

Request

POST /api/dita-compare/v1/compare/mts
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="inA.zip"
Content-Type: application/zip

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

inA/inA.ditamap

--boundary-id
Content-Disposition: form-data; name="inputB"; filename="inB.zip"
Content-Type: application/zip

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

inB/inB.ditamap
--boundary-id
Content-Disposition: form-data; name="async"
true
--boundary-id