Asynchronous Operations

Synchronous mode is used when the response is obtained quickly and where the Delta is returned as part of the response.

However in other cases asynchronous mode is useful:

If there is a risk of HTTP timeout
When using HTTP or Cloud IO - as the REST service will need to make HTTP requests to retrieve these resources
Using large inputs
When the result is needed somewhere other than where the response is returned
Where progress, logging or resource consumption information is needed
When multiple operations can be started at once

JSON Request

An asynchronous operation will use the async element to specify the optional values callback and output in addition to the elements used in the synchronous operations.

callback provides a callback URL that the REST service will make a GET request to after the comparison is complete. This is detailed in Callbacks below.
output allows you to specify a location for the result to be written to. For more information see I/O Types

The response will consist of the created Job, and a Location header pointing to where you can poll the Job status.

Request

JS

{
  "a": {
    "type": "http",
    "uri": "http://www.example.com/file1.json"
  },
  "b": {
    "type": "http",
    "uri": "http://www.example.com/file2.json"
  },
  "async": {
    "callback": "http://www.example.com/comparison-callback",
    "output": {
      "type": "file",
      "path": "/Users/exampleUser/Documents/result.json"
    }
  }
}

Response

JS

HTTP/1.1 202 Accepted
Location:  /api/json/v1/jobs/12346124
{
    "startTime": "2020-02-04T11:17:30.586+0000",
    "creationTime": "2020-02-04T11:17:30.586+0000",
    "jobId": "12346124",
    "numberOfStages": 0,
    "progressInPercentage": 0.0,
    "jobStatus": "STARTED"
}

Form Request

When using multipart/form-data, set the parameter async to true.

You can also use the parameters callback and keepResult in a similar fashion to JSON async requests.

CODE

.....
Content-Disposition: form-data; name= "async"
true
--boundary
Content-Disposition: form-data; name= "callback"
http: //www.example.com/comparison-callback
--boundary
Content-Disposition: form-data; name= "output"
/Users/exampleUser/Documents/out.xml
--boundary
 .....

Jobs

For each async comparison a Job is created. The jobs can be read from the /jobs/{jobId} endpoint. For example, you can poll for the Job's status:

Request

CODE

GET /api/xml-compare/v1/jobs/12346124

Response

JS

{
    "startTime": "2020-02-04T11:24:03.734+0000",
    "creationTime": "2020-02-04T11:24:03.734+0000",
    "jobId": "12346124",
    "numberOfStages": 19,
    "progressInPercentage": 52.0,
    "pipelineStage": "word-in",
    "jobStatus": "COMPARISON_RUNNING"
}

You can see the pipeline is currently running the Input Filter Chain for Input B, but some time later...

Response

JS

{
    "startTime": "2020-02-04T11:24:03.734+0000",
    "creationTime": "2020-02-04T11:24:03.734+0000",
    "finishedTime": "2020-02-04T11:24:10.846+0000",
    "comparisonTime": "7112 ms",
    "jobId": "12346124",
    "numberOfStages": 19,
    "progressInPercentage": 100.0,
    "pipelineStage": "jsondelta",
    "jobStatus": "FINISHED",
    "output": {
        "type": "http",
        "size": 1802959,
        "uri": "http://0.0.0.0:8080/api/json/v1/downloads/12346124"
    }
}

...the comparison is now finished - with an output object listing the details of accessing the result.

Job Model

The Job contains the following objects:

Object	Description
`creationTime`	ISO 8601 timestamp of the time the Job was created.
`startTime`	ISO 8601 timestamp when the comparison started. Depending on the number of queued jobs, there may be significant time between `creationTime` and `startTime`
`finishedTime`	ISO 8601 timestamp of when the comparison finished.
`comparisonTime`	Time in ms the comparison took, as a string - e.g. "123 ms".
`jobStatus`	An enumeration of the state of the operation. When using a three-way operation (graft, three-way merge) these states are available: QUEUED SUBMITTED STARTED EXTRACTING SAVING SUCCESS FAILED CANCELLED When using a two-way operation (compare, merge, patch) you get a more detailed list of possible states: QUEUED SUBMITTED STARTED INPUTS_LOADING_A INPUTS_LOADING_B INPUT_FILTER_CHAIN_A INPUT_FILTER_CHAIN_B COMPARISON_RUNNING OUTPUT_FILTERS SAVING SUCCESS FAILED CANCELLED
`jobId`	The ID of the Job
`links / link`	HATEOAS links containing a `href` URI and a `rel` describing its meaning. A rel of "cancel" indicates you can use `HTTP DELETE` to cancel the Job, whereas "result" indicates the endpoint you should call `GET` on to receive result information.
`output`	Specifies where the result has been output. See I/O Types for more information.
`error`	Contains error information if an error happened. See Errors Page for more information.
Compare Specific
`numberOfStages`	Number of stages in the pipeline, as an integer.
`pipelineStage`	The current pipeline stage of the comparison.
`progressInPercentage`	Percentage of progress in the pipeline, as an integer. Note: numbers are approximate, and are based on the number of stages in the pipeline. Individual stages will vary in length of time they take to complete.
Merge Specific
`phaseDescription`	Lists the current stage of the merge operation (e.g. processing the Ancestor version).
`stageDescription`	Lists the current filter being used.
`processingTime`	The time the actual merge took while processing, in nanoseconds.

When using Cloud I/O output will contain the Cloud I/O information provided minus the client ID / secret information for security reasons, for example:

JS

"output": {
        "type": "s3",
		"region": "EU-WEST-1",
        "bucket": "DeltaXML-Bucket",
        "fileName": "output.json"
    }

If not using Cloud I/O for the output, then it will contain a uri and size (which provides the result size in bytes - as an integer). For example:

JS

"output": {
        "type": "http",
        "size": 143,
        "uri": "http://0.0.0.0:8080/api/json/v1/downloads/3318c183-b7db-42f2-bc2e-9af867f85e99"
}

If the comparison failed, an error element will contain details of the failure, including a stack trace which can help diagnose the issue. The size of the result is reported in terms of bytes.

A GET request to the output uri will then complete the asynchronous lifecycle:

Request

CODE

GET /api/json/v1/downloads/123456

Response

CODE

HTTP/1.1 200 OK
{
    "a": "my data",
    "b": "bbc 2",
    "name": "Mr John Smith",
    "age": 22,
    "hobbies": [
        "Badminton",
        "guitar",
        "reading",
        "Baseball"
    ],
    "pet": "dog",
    "added": "element"
}

Note

If the pipeline POST request specified an output file location, the output file will be available at that location after a successful asynchronous comparison. A GET request from the downloads resource will merely provide the same file from that location.

Cancelling a Job

Jobs can be cancelled while they are queued or running, this is indicated through a HATEOAS link in the Job info, for example:

Response

JS

{
    "startTime": "2020-02-04T11:24:03.734+0000",
    "creationTime": "2020-02-04T11:24:03.734+0000",
    "jobId": "12346124",
    "numberOfStages": 19,
    "progressInPercentage": 52.0,
    "pipelineStage": "word-in",
    "jobStatus": "COMPARISON_RUNNING",
	"links": [
    	{
      	"rel": "cancel",
      	"href": "/api/json/v1/jobs/12346124"
    	}
  	]
}

It is invoked by using a DELETE request to the specified Job:

Request

CODE

DELETE /api/json/v1/jobs/12346124

The response will be the Job, note the jobStatus is now DELETED:

Response

JS

{
    "startTime": "2020-02-04T16:36:45.179+0000",
    "creationTime": "2020-02-04T16:36:37.472+0000",
    "jobId": "12346124",
    "numberOfStages": 19,
    "progressInPercentage": 52.0,
    "pipelineStage": "word-in",
    "jobStatus": "DELETED"
}

Callbacks

If the user registered a callback URL with the comparison request, the REST service will attempt an HTTP GET to that URL on completion of the comparison.

In this example the callback URL "http://www.example.com/comparison-callback" was registered in the comparison request - we will add a request parameter of jobId which allows the Job resource to be located:

Request

CODE

GET http://www.example.com/comparison-callback?jobId=12346124