Topic Comparison Example

Synchronous Comparison Example

Comparison Model

When specifying a comparison using XML or JSON structured request, 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/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)

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

<?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>

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 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.

For example:

Request

CODE

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