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.

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.

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

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.

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>"
}

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

# 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

# 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

# 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'

# 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'

# 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

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>

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>

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