Specifying Comparisons
To invoke a comparison you POST parameters to the specified DITA Compare pipeline, in either JSON or XML form.
Comparison Example
Here is a simple synchronous example (asynchronous comparison is detailed in more detail on this page):
Request (XML)
<comparison>
<inputA type="file">
<path>/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/inputA.dita</path>
</inputA>
<inputB type="file">
<path>/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/inputB.dita</path>
</inputB>
<configuration type="file">
<path>/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/config.xml</path>
</configuration>
</comparison>Request (JSON)
{
"inputA": {
"type": "file",
"path": "/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/inputA.dita"
},
"inputB": {
"type": "file",
"path": "/usr/local/deltaxml/DeltaXML-DITA-Compare-11_0_0/resources/inputB.dita"
},
"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 an DITA topic describing the changes between the inputs specified in the request.
Response
<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "http://docs.oasis-open.org/dita/v1.1/OS/dtd/topic.dtd">
<topic id="topic-1">
<title>DeltaXML DITA Compare - taking control of document changes </title>
<body>
<p status="unchanged">This sample document shows some of the benefits of DeltaXML DITA
Compare, which shows revisions in all your DITA documents. DeltaXML DITA Compare takes
the pain out of tracking and documenting changes in all DITA documents.</p>
<p status="unchanged">You can simply execute DeltaXML DITA Compare and provide it with two
versions of, say, a DITA topic and it will generate a new topic file which shows all the
changes. Added, deleted and changed text will be highlighted. This simple example shows
how this works.</p>
<p>This document represents Version <ph status="deleted" rev="deltaxml-delete">1</ph><ph
status="new" rev="deltaxml-add">2</ph>. You will see that when 'Version 1' is
changed to 'Version 2', the change is shown.</p>
</body>
</topic>Comparison Model
When specifying a comparison, 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. | |
Form Input
In addition to requests in structured XML or JSON format, multipart/form-data can also be used.
For example:
Request
POST /api/dita-compare/v1/compare/topic
Content-Type: multipart/form-data; boundary=boundary-id
Content-Length: number_of_bytes_in_entire_request_body
--boundary-id
Content-Disposition: file; filename="file1.dita"
Content-Size: 98344
Content-Type: application/xml
... XML ...
--boundary-id
Content-Disposition: file; filename="file2.dita"
Content-Size: 92224
Content-Type: application/xml
... XML ...
--boundary-id
Content-Disposition: file; filename="configuration.xml"
Content-Size: 32224
Content-Type: application/xml
... XML ...
--boundary-id
Content-Disposition: form-data; name="async"
true
--boundary-id
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 XML |
inputB (required) | Input B Can be specified in either a file path, a HTTP URI, or raw XML |
configuration | Configuration file Can be specified in either a file path, a HTTP URI, or raw XML |
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. |