TrophyCustomer's Canvas is honored with a 2020 InterTech Technology Award! Learn more 

Preflight Web API

The Preflight Web API is a REST API that allows you to verify that users' print files are compatible with your printing equipment. You can define preflight rules and check if print files match those rules by using HTTP requests. The Preflight Web API allows you to:

After you have deployed the Preflight Tool, you can navigate to <your-instance-url>/swagger and explore the interactive Web API in your browser. You can also download a code sample demonstrating how to validate print files.

This Web API doesn't require authentication. In the following examples, we use the appUrl variable that represents a folder on your server where you deployed this tool, for example, http://example.com/pt/.

Uploading a File to the Server

To validate that print files are compatible with your printing equipment, you must first upload them to your server. This endpoint allows for uploading a print file.

Request type

[POST]

URL

~/api/files/upload

Example call

You can pass and upload a file as follows:

JavaScript
<input type="file" id="file" onchange="upload(event)"/>
...
const upload = async (event) => {
    const file = event.target.files[0];
    const formData = new FormData();
    formData.append('file', file);

    const response = await fetch(appUrl + "api/files/upload?dpi=200", {
        method: "POST",
        body: formData
    });
    console.log(await response.json());
}

Success response

As a result, you get the GUID that your print file obtained after saving it on the server.

Status Code: 200 OK
Content:
[
    "425a3537-2e59-450d-bbc2-484fcd3d63bd.pdf"
]

Getting a File from the Server

To download a file from the server, you can get a file stream by the file's GUID.

Request type

[GET]

URL

~/api/files/get/{GUID}

Required URL Param

GUID - a file identifier with an extension.

Example call

HTML
<embed src="http://example.com/pt/api/files/get/425a3537-2e59-450d-bbc2-484fcd3d63bd.pdf" type="application/pdf" width="800px" height="800px" />

In the following section, you can learn how to use this endpoint to perform the preflight check.

Success response

If the result is successful, this method returns the content of the file in a file stream.

Status Code: 200 OK
Content-type: application/octet-stream

Checking the Preflight Rules

You can pass an array of preflight rules and a URL that link to a print file to check whether this file matches the rules. In the current implementation, you can check the following rules through this Web API:

Request type

[POST]

URL

"~/api/rules/check"

Request Payload

To validate your print file, you can pass its name, resolution, and required rules in the request body in the following format.

{
    "file": "http://example.com/pt/api/files/get/425a3537-2e59-450d-bbc2-484fcd3d63bd.pdf",
    "dpi": 200,
    "rules": [
        {
            "type": "embeddedfonts"
        }
    ]
}

Example call

JavaScript
// The link to the print file.
const file = appUrl + "api/files/get/425a3537-2e59-450d-bbc2-484fcd3d63bd.pdf";
// Resolution of the print file.
const dpi = 300;
// The required color space and page orientation.
const rules = [
    {
        "type": "colorspace",
        "params": {
            "allowedColorSpaces": ["cmyk"]
        }
    },
    {
        "type": "sameorientation"
    }
];
// Check the file.
const check = async () => {
    const response = await fetch(appUrl + "api/rules/check", {
        method: "post",
        body: JSON.stringify({ dpi, file, rules }),
        headers: {
            'Content-Type': 'application/json'
        }
    });
    const result = await response.json();
    // Output the resulting array, where each element is an array of preflight results for a page.
    console.log(result);
}

Success response

This endpoint returns an array, where each element corresponds to a page in the print file. These elements contain validation results. The result of validation of a one-page PDF file may look as follows:

Status Code: 200 OK
Content:
[
    [
        {
            name: "colorspace",
            result: false,
            expected: ["cmyk"],
            actual: ["rgb"]
        },
        {
            name: "sameorientation",
            result: true,
            expected: ["horizontal"],
            actual: []
        }
    ]
]

Getting the Build Info

You can get the version, build date, build configuration, and application name by using this endpoint. You may need these details when contacting our support team.

Request type

[GET, HEAD]

URL

~/api/info

Example call

JavaScript
const info = async () => {
    const response = await fetch(appUrl + "api/info");
    console.log(await response.json());
};

Success response

Status Code: 200 OK
Content:
{
    version: "1.7.2",
    buildDate: "9/9/2020",
    configuration: "Release",
    appName: "Preflight"
}

See Also

Manual

Downloads