{{sidenavigation.sidenavigationExpandLabel}}
{{getMsg('Help_YouAreHere')}}: {{page.title}} {{page.title}}

{{$root.getMsg("downLoadHelpAsPdf")}} {{helpModel.downloadHelpPdfDataStatus}}

Compare

Configures and starts a new comparison. The response of the server may be delayed until the comparison is done, depending on the value of the result-parameter. The request can also be send using the method POST.

Implementation note

Just like any other web API request, this request will create a new session on the server for the requesting user. If used for automated comparisons this may lead to an excessive amount of server sessions and poor performance due to the authentication overhead. In addition, the web server defender plugin may block the requests due to its session limit.

It's highly recommended to store the users session cookies and use these cookies for subsequent requests. This improves the performance and memory efficiency.

GET /api/comparison/compare

Starts a new comparison with the given request parameters using the HTTP GET method

REQUEST Parameter Optional Value Description
file1 mandatory URL (encoded) Defines the first document for the comparison
or PDF file if using POST
file2 mandatory URL (encoded) Defines the second document for the comparison
or PDF file if using POST
profile optional URL1) or profile name Name of an available comparison profile or a URL for an XML-File containing a comparison profile
name optional Name for the comparison. If a comparison has a name set, it will not be deleted automatically. Comparisons without a name are deleted regularly. You can accelerate the cleanup using the free parameter.
result optional empty (Default) The GUID is sent back as text/plain, server will respond immediately, when using a different result type, you may additionally use the types specific parameters as well.
webgui Redirects to the WebGUI, server will respond immediately
pdf Returns the comparison result as PDF file; The response will be delayed until the comparison is done
log Returns the log output of the current comparison; The response will be delayed until the comparison is done
count Returns the number of differences as plain text; The response will be delayed until the comparison is done
report Returns the comparison result as PDF report file.
free optional empty Deletes the results immediately after the comparison, even if the name is set. Therefore a result parameter should be set, or the comparison data would be lost.

Note: The comparison result can be obtained using the command /<GUID>/result/<type> where several additional options can be provided. You can use the same parameters in this request as well.

POST /api/comparison/compare

The same parameters as above can be used to send a POST method request. Furthermore the POST method supports some additional modes, namely sending the files to compare using a multipart request. These requests contain the complete PDF (or other types) that will be compared. In addition the comparison profile can be sent using a prepared file as well.

Last but not least a JSON configuration is supported. It can either be sent alongside the files the compare or using a Content-Type: application/json request. The structure is as followed - the parameters are basically the same as above, including the optionality:

{
  "profile": {
    "url": "<URL to fetch file to compare>",
    "headers": {
      <optional list of request headers required to fetch data from the URL>
      "Authorization": "Basic cGFzc3dvcmQK"
    }
  },
  "file1": {
    <same as profile with the following addition>
    "password": "<optional, base64 encoded password string to open PDF file>"
  },
  "file2": {
    <same as file1>
  },
 
  "name": "<the name of the comparison, e.g. for publishing>",
  "profileName": "<alternative name of the profile to use instead of 'profile' struct>",
  "free": "<true|false><optional boolean value to not store the comparison>",
  "result": "<optional result type>"
}

Examples

The following examples will give an overview of the possibilities on how to send requests to compare PDF files.

Example Request: <GUID> response

# REQUEST:
# Use user:password for authorization
GET /api/comparison/compare?file1=http://myserver.com/pdf-file1.pdf&file2=http://myserver.com/pdf-file1.pdf HTTP/1.1
Authorization: Bearer VGhpcyBpcyBqdXN0IGEgZGVtbyBhY2Nlc3MgdG9rZW4u
 
# RESPONSE:
HTTP/1.2 200 OK
Content-Type: text/plain
TG9yZW0gaXBzdW0gZG9sb3Igc2l0IG1ldC4

Example Request: Count response

# REQUEST
# Use user:password for authorization
GET /api/comparison/compare?file1=http://myserver.com/pdf-file1.pdf&file2=http://myserver.com/pdf-file1.pdf&result=count HTTP/1.1
Authorization: Bearer VGhpcyBpcyBqdXN0IGEgZGVtbyBhY2Nlc3MgdG9rZW4u
 
# RESPONSE:
HTTP/1.2 200 OK
Content-Type: text/plain
1000

Application Example: Start a comparison

# Browser access: use the following URL
http://127.0.0.1:9900/api/comparison/compare?file1=https://www.inetsoftware.de/_media/products/clear-reports/documentation/2016/ad-hoc-reporting.pdf&file2=https://www.inetsoftware.de/_media/products/clear-reports/documentation/2015/ad-hoc-reporting.pdf&result=pdf
 
# Shell access using curl
curl -Lsu <USERNAME>:<PASSWORD> -d 'file1=https://www.inetsoftware.de/_media/products/clear-reports/documentation/2016/ad-hoc-reporting.pdf&file2=https://www.inetsoftware.de/_media/products/clear-reports/documentation/2015/ad-hoc-reporting.pdf' 'http://127.0.0.1:9900/api/comparison/compare'

Application Example: Post PDF files and start a comparison

# Shell access using curl
curl -Lsu <USERNAME>:<PASSWORD> -F 'file1=\@/path/to/file1.pdf' -F 'file2=\@/path/to/file2.pdf' 'http://127.0.0.1:9900/api/comparison/compare'

Application Example: Post a JSON file with URLs to compare

# REQUEST
POST /api/comparison/compare HTTP/1.1
Authorization: Bearer VGhpcyBpcyBqdXN0IGEgZGVtbyBhY2Nlc3MgdG9rZW4u
Content-Type: application/json
Content-Length: 500
 
{
  "file1": {
    "url": "http://myserver.com/pdf-file1.pdf",
    "headers": {
      "Authorization": "Basic cGFzc3dvcmQK"
    },
    "password": "cGFzc3dvcmQK"
  },
  "file2": {
    "url": "http://myserver.com/pdf-file1.pdf",
    "headers": {
      "Authorization": "Basic cGFzc3dvcmQK"
    },
    "password": "cGFzc3dvcmQK"
  },
  "name": "My Comparison"
}
 
# RESPONSE:
HTTP/1.2 200 OK
Content-Type: text/plain
TG9yZW0gaXBzdW0gZG9sb3Igc2l0IG1ldC4

Application Example: Show compare GUI from a web application

For this sample you need to enable your web server as a "Allowed Cross Origins" in the configuration manager web interface.

<html>
<head>
<title>Sample</title>
<script>
var pdfcServer = 'http://comparisonserver:9900/';
function showComparisonResult(){
    var url = pdfcServer + 'api/comparison/compare';
    var xhr = new XMLHttpRequest();
    xhr.open('POST', url, true);
 
    // Option 1:
    // If your user is already logged in on the current website, set this flag to pass 
    // the auth and cookies to the comparison server.
    //    xhr.withCredentials = true;
 
    // Option 2:
    // In case there is no existing auth or session cookie for the comparison server
    // set a basic authentication header.
    // This will set "user:password" as authorization, change the auth token to a valid.
    xhr.setRequestHeader('Authorization', 'Basic dXNlcjpwYXNzd29yZA==');
 
    xhr.send( new FormData( document.forms.compare ) );
    xhr.onreadystatechange = function () {
        if (xhr.readyState == XMLHttpRequest.DONE) {
            // the default response is the ID of the comparison
            var guid = xhr.responseText.replace(/^"(.*)"$/, '$1');
            if (xhr.status == 200) {
                window.open(pdfcServer + 'comparison/' + guid);
            } else {
                alert( guid );
            }
        }
    };
}
</script>
</head>
<body>
<form action="javascript:showComparisonResult();" method="POST" name="compare">
<input type="file" name="file1" />
<input type="file" name="file2" />
<input type="submit" value="Compare" />
</form>
</body>
</html>

Application Example: Post PDF files and show compare GUI from a web application

For this sample you need to enable your web server as a "Allowed Cross Origins" in the configuration manager web interface.

The webpage collects PDF files and sends them using a post request.

<html>
<head>
<title>Sample</title>
<script>
var pdfcServer = 'http://localhost:9900/';
function showComparisonResult(){
    var url = pdfcServer + 'api/comparison/compare';
    var xhr = new XMLHttpRequest();
    xhr.open('POST', url, true);
    xhr.withCredentials = true;
 
    // Set "user:password" as basic authorization header
    xhr.setRequestHeader('Authorization', 'Basic dXNlcjpwYXNzd29yZA==');
    xhr.send();
    xhr.onreadystatechange = function () {
        if (xhr.readyState == XMLHttpRequest.DONE) {
            var guid = xhr.responseText;
            if (xhr.status == 200) {
                window.open(pdfcServer + 'comparison/' + guid);
            } else {
                alert( guid );
            }
        }
    };
}
</script>
</head>
<body>
<form action="javascript:showComparisonResult();" method="POST">
<input type="file" name="file1" />
<input type="file" name="file2" />
<input type="submit" calue="Compare" />
</form>
</body>
</html>

Application Example: Post PDF with Powershell and .NET

Up until now, the Powershell does not provide support for multipart uploads. That is why we have to implement the upload using the .NET System.Net.Http.HttpClient class.

# Function to add multiple files to multipart
function Add-FormFile {
    param ([string]$Path, [string]$Name)
 
    if ($Path -ne "")
    {
        $FileStream = [System.IO.File]::OpenRead($Path)
        $FileName = [System.IO.Path]::GetFileName($Path)
        $FileContent = [System.Net.Http.StreamContent]::new($FileStream)
        $MultipartFormData.Add($FileContent, $Name, $FileName)
    }
}
 
# URL to PDFC Server
$urlBase = "http://localhost:9900"
$url = $urlBase + "/api/comparison/compare"
 
# File to upload
$file1 = 'C:\temp\file1.pdf'
$file2 = 'C:\temp\file2.pdf'
 
$user = ''
$password = ''
$credential = [System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes($user + ":" + $password))
 
# Create the HTTPClient with Basic authentication
$ClientMessageHandler = New-Object System.Net.Http.HttpClientHandler
$Client = [System.Net.Http.HttpClient]::new($ClientMessageHandler)
$Client.DefaultRequestHeaders.Authorization = New-Object System.Net.Http.Headers.AuthenticationHeaderValue("Basic", $credential);
 
# Accept header to application/json
$Accept = New-Object System.Net.Http.Headers.MediaTypeWithQualityHeaderValue("application/json");
$Client.DefaultRequestHeaders.Accept.Add( $Accept )
 
# Create Multipart Content
$MultipartFormData = New-Object System.Net.Http.MultipartFormDataContent
 
# Add the files. Optionally add "profile" if required
Add-FormFile $file1 "file1"
Add-FormFile $file2 "file2"
 
# optional Parameter values
$ParameterValues = @{
    name = "my comparison"
} | ConvertTo-Json -Compress
 
# Add Parameter values as additional json multipart 
$Params = New-Object System.Net.Http.StringContent( $ParameterValues );
$Params.Headers.ContentType = "application/json"
$MultipartFormData.Add($Params, "form-data")
 
# Post data to server
$Response = $Client.PostAsync($url, $MultipartFormData)
$Response.Result.EnsureSuccessStatusCode()
 
# Read Response content
$Result = $Response.Result.Content.ReadAsStringAsync().Result
echo $Result
 
# Depending on output, de-serialize JSON
echo $Result | ConvertFrom-Json
1)
should be URL-encoded
 
i-net PDFC
This application uses cookies to allow login. By continuing to use this application, you agree to the use of cookies.


Help - /compare