Comparison request

To invoke a comparison you POST parameters to the specified pipeline using multipart/form-data.

For example:

Request

CODE

POST /api/html-compare/v1/pipelines/delta HTTP/1.1
--boundary
Content-Disposition: form-data: name="inputA"
/Users/example/file1.html
--boundary
Content-Disposition: form-data: name="inputB"
/Users/example/file2.html
--boundary
Content-Disposition: form-data; name="configuration"
/Users/example/config.xml
--boundary
Content-Disposition: form-data; name="output"
/Users/example/out.html
--boundary

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 for setting parameters. If non is specified default configuration will be used Can be specified in either a file path, a HTTP URI, or raw XML
output	An optional file path to write the output to E.g. "/Users/exampleUser/Documents/test.xml"
callback	Callback URL called after comparison is complete E.g. http://www.example.com

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/html-compare/v1/jobs/e1650849-d07b-478c-bfa1-5d6938960391

Response (XML)

CODE

<job>
    <startTime>2024-08-15T07:33:58.912+0000</startTime>
    <creationTime>2024-08-15T07:33:58.804+0000</creationTime>
    <jobId>e1650849-d07b-478c-bfa1-5d6938960391</jobId>
    <numberOfStages>77</numberOfStages>
    <progressInPercentage>12.0</progressInPercentage>
    <jobStatus>INPUT_FILTER_CHAIN_B</jobStatus>
</job>

Response (JSON)

CODE

{
  "startTime": "2024-08-15T07:33:58.912+0000",
  "creationTime": "2024-08-15T07:33:58.804+0000",
  "jobId": "e1650849-d07b-478c-bfa1-5d6938960391",
  "numberOfStages": 77,
  "progressInPercentage": 12,
  "jobStatus": "INPUT_FILTER_CHAIN_B"
}

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

Response (XML)

CODE

<job>
    <startTime>2024-08-15T07:33:58.912+0000</startTime>
    <creationTime>2024-08-15T07:33:58.804+0000</creationTime>
    <finishedTime>2024-08-15T07:34:14.960+0000</finishedTime>
    <comparisonTime>16048 ms</comparisonTime>
    <jobId>e1650849-d07b-478c-bfa1-5d6938960391</jobId>
    <numberOfStages>84</numberOfStages>
    <progressInPercentage>100.0</progressInPercentage>
    <jobStatus>FINISHED</jobStatus>
    <output type="http">
        <uri>http://0.0.0.0:8080/api/html-compare/v1/downloads/e1650849-d07b-478c-bfa1-5d6938960391</uri>
        <size>242478</size>
        <authorizationHeader/>
    </output>
</job>

Response (JSON)

CODE

{
  "startTime": "2024-08-15T07:34:14.912+0000",
  "creationTime": "2024-08-15T07:34:14.804+0000",
  "finishedTime": "2024-08-15T07:34:14.960+0000",
  "comparisonTime": "16048 ms",
  "jobId": "e1650849-d07b-478c-bfa1-5d6938960391",
  "numberOfStages": 84,
  "progressInPercentage": 100,
  "jobStatus": "FINISHED",
  "output": [
    {
      "type": "http",
      "uri": "http://0.0.0.0:8080/api/html-compare/v1/downloads/e1650849-d07b-478c-bfa1-5d6938960391",
      "size": "242478",
      "authorizationHeader": {}
    }
  ]
}

...the comparison is now finished - with a uri link available to view 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 comparison. States include: QUEUED STARTED INPUTS_LOADING_A INPUTS_LOADING_B INPUT_FILTERS COMPARISON_RUNNING OUTPUT_FILTERS SAVING FINISHED FAILED CANCELLED
`jobId`	The ID of the Job
`numberOfStages`	Number of stages in the pipeline, as an integer.
`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.
`output`	Specifies where the result has been output to.
`error`	Contains error information if an error happened. See Errors Page for more information.

The outputwill contain a uri and size (which provides the result size in bytes - as an integer). For example:

CODE

<output type="http">
    <uri>http://0.0.0.0:8080/api/html-compare/v1/downloads/e1650849-d07b-478c-bfa1-5d6938960391</uri>
    <size>242478</size>
</output>

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/html-compare/v1/downloads/e1650849-d07b-478c-bfa1-5d6938960391

Response

CODE

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
    <head>...</head>
    <body>...</body>
</html>

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.

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

Request

CODE

DELETE /api/html-compare/v1/jobs/e1650849-d07b-478c-bfa1-5d6938960391

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

Response

CODE

<job>
    <startTime>2024-08-15T07:33:58.912+0000</startTime>
    <creationTime>2024-08-15T07:33:58.804+0000</creationTime>
    <finishedTime>2024-08-15T07:34:14.960+0000</finishedTime>
    <comparisonTime>16048 ms</comparisonTime>
    <jobId>e1650849-d07b-478c-bfa1-5d6938960391</jobId>
    <numberOfStages>84</numberOfStages>
    <progressInPercentage>100.0</progressInPercentage>
    <jobStatus>DELETED</jobStatus>
    <output type="http">
        <uri>http://0.0.0.0:8080/api/html-compare/v1/downloads/e1650849-d07b-478c-bfa1-5d6938960391</uri>
        <size>242478</size>
        <authorizationHeader/>
    </output>
</job>

Response

CODE

{
  "startTime": "2024-08-15T07:34:14.912+0000",
  "creationTime": "2024-08-15T07:34:14.804+0000",
  "finishedTime": "2024-08-15T07:34:14.960+0000",
  "comparisonTime": "16048 ms",
  "numberOfStages": 84,
  "progressInPercentage": 100,
  "jobStatus": "DELETED",
  "output": [
    {
      "type": "http",
      "uri": "http://0.0.0.0:8080/api/html-compare/v1/downloads/e1650849-d07b-478c-bfa1-5d6938960391",
      "size": "242478",
      "authorizationHeader": {}
    }
  ]
}