iText DITO Docker API (iText_DITO 1.3)

The iText DITO SDK for Docker image allows you to use iText DITO conveniently from various environments. It enables you to produce PDFs from your output templates.

How to use the iText DITO SDK for Docker image

Note: you need to specify the version explicitly when using the pull command, e.g.:

docker pull itext/dito-sdk:{version}

Start the SDK

To start the docker image run the following command:

docker run -it --name dito-sdk-instance
         -v {path to config directory}:/etc/opt/dito/shared
         -v {path to work directory}:/var/opt/dito
         -v {path to log directory}:/var/log/dito
         -p {port on host}:8080
         itext/dito-sdk:{version}

config directory - the directory that contains iText DITO license, by default it will look for license.xml file, but you can override it by setting the DITO_LICENSE_FILE environment variable during run, for example:

docker run {other options} -e DITO_LICENSE_FILE=dito.xml itext/dito-sdk:{version}

Note: For consistency in API behaviour when updating to a newer version of the SDK it is advised to specify the desired API version in X-DITO-API-Version header for all requests. For more info see API versions descriptor documentation. If you're using Azure, you may get an error message that the license key cannot be found. To resolve this, you will need to enable volume mounting using the WEBSITES_ENABLE_APP_SERVICE_STORAGE=true environment variable.

docker kill --signal=SIGTERM {containerId}

You can also use another standard command:

docker stop -t 30 {containerId}

This command sends the SIGTERM signal to the SDK process inside the Docker container, then waits for the specified time in seconds (10 by default). If the SDK doesn't manage to finish its shutdown within that time period, SIGKILL is sent to the kernel and the SDK process is killed.

Web API reference

PDF Producer Resource

Actions

URI

Methods

/api/pdf-producer

POST - creates PDFs from one of the template package's templates and data.
Acceptable request types:

application/json - production request descriptor

Response type:

application/json - production response descriptor

Response codes:

200 OK - PDF successfully created; 400 Bad Request - one of the descriptor parameters is invalid

Production request descriptor

Name	Type	Description
templateProjectPath	string (path)	Path to the template project (relative to shared work directory)
templateName	string	Name of the template inside the template project
data	json optional	Data used for production. If specified as string than it is treated as path to data file (relative to shared work directory), otherwise is treated as direct template data. If not specified then empty data is is sent: {}
path	string (path) optional	The suggested path to the resulting PDF file, relative to the work directory. If a file already exists than a new path will be generated. All intermediate directories are created. If not specified, then file names are generated automatically from defaultVersion UTC data in the format: yyyy-MM-dd-HH.mm.ss.nnnnnnnnn.pdf
properties	production properties descriptor optional	The PDF production properties

Production response descriptor

Name	Type	Description
path	string(path)	Path to the produced PDF relative to work directory.

Production properties descriptor

Name	Type	Description
pdfVersion	string (enum) optional	Target PDF version. Valid values are: 1.7 (default) 2.0

License resource

Actions

URI	Methods
/api/license	GET- gets loaded license info Response type: application/json - license descriptor Response codes: 200 OK

License descriptor

Name	Type	Description
expirationDate	date	Expiration UTC date in format: yyyy-MM-dd
remaining	dictionary	Dictionary from limit type to long number of remaining events. Possible limit types: document page

Status resource

Actions

URI	Methods
/api/status	GET- gets server status Response type: application/json - status descriptor Response codes: 200 OK

Status descriptor

Name	Type	Description
sdkVersion	string	Version of the iText DITO SDK in the format: major.minor.build
apiVersions	API versions descriptor	Information about API versions.
health	dictionary	The dictionary with server health checks

API versions descriptor

Each request can specify the desired API version in the X-DITO-API-Version header.

Name	Type	Description
default	string	The default API version that will be used if the X-DITO-API-Version header is not specified.
maximumSupported	string	The maximum supported API version. If the version specified in X-DITO-API-Version header is newer than the maximum supported version the request will fail.
minimumSupported	string	The minimum supported API version. If the version specified in X-DITO-API-Version header is older than the minimum supported version the request will fail.

Examples

Running SDK

On Windows

docker run -it --name dito-sdk-example
         -v D:\docker\dito\config:/etc/opt/dito/shared
         -v D:\docker\dito\work:/var/opt/dito
         -v D:\docker\dito\log:/var/log/dito
         -p 42:8080
         itext/dito-sdk:1.1.8

D:\docker\dito\config - a folder with license.xml file.

D:\docker\dito\work - a working folder where all project files and data samples should be placed.

D:\docker\dito\log - a log folder where service logs will be placed.

On Linux

docker run -it --name dito-sdk-example
         -v /home/docker/dito/config:/etc/opt/dito/shared
         -v /home/docker/dito/work:/var/opt/dito
         -v /home/docker/dito/log:/var/log/dito
         -p 42:8080
         itext/dito-sdk:1.1.8

/home/docker/dito/config - a folder with license.xml file.

/home/docker/dito/work - a working folder where all project files and data samples should be placed.

/home/docker/dito/log - a log folder where service logs will be placed.

Requests

For next requests all paths are relative to working directory (/home/docker/dito/work on Linux or D:\docker\dito\work on Windows assuming service is run with commands above) The dummy.dito is an example iText DITO project that is placed in the working directory. The sample.json is a data sample for it that is placed in the same working directory.

Produce PDF from project file and data in working directory

Request

Response

POST localhost:42/api/pdf-producer

Content-Type application/json

Body
{
    "templateProjectPath": "dummy.dito",
    "templateName": "output",
    "data": "sample.json"
}

200 OK

Content-Type application/json

Body
{
    "path": "2019-09-23-13.00.44.472000000.pdf"
}

Produce PDF with 2.0 version and custom output path from project file in working directory and data embedded in the request

Request

Response

POST localhost:42/api/pdf-producer

Content-Type application/json

Body
{
    "templateProjectPath": "dummy.dito",
    "templateName": "output",
    "data": {
        "bind": "from request"
    },
    "path": "custom/path/to/file.pdf",
    "properties": {
        "pdfVersion": "2.0"
    }
}

200 OK

Content-Type application/json

Body
{
    "path": "custom/path/to/file.pdf"
}

Get loaded license info

Request

Response

GET localhost:42/api/license

200 OK

Content-Type application/json

Body
{
    "expirationDate": "2020-09-23",
    "remaining": {
        "page": 999980
    }
}