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
Starts a new comparison with the given request parameters using the HTTP GET
method
REQUEST Parameter | Optional | Value | Description |
---|---|---|---|
file1 | mandatory | URL1) or PDF file2) | Defines the first document for the comparison |
file2 | mandatory | URL3) or PDF file4) | Defines the second document for the comparison |
profile | optional | URL5) 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 | |
result | optional | empty (Default) | The GUID is sent back as text/plain, server will respond immediately |
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 | ||
free | optional | empty | Doesn't store the comparison |
Note: The comparison result can be obtained using the command /<GUID>/result/<type> where several additional options can be provided.
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