Skip to main content

Integrate via REST API

The REST API lets you schedule jobs and get service status information. The REST API is also used by the other clients, such as the shell client and the watched folder.

tip

For easy integration with existing Windows-based systems, a simplified REST interface is provided by input connectors: REST input connector and REST input JSON.

You define the service base URL of the REST API in the Service configuration, with the service-host-address property. The default value is http://localhost:13033/conversion/v1.0/rest.

API security​

By default, the API is available on the local machine only. If you want to access it remotely, you need to configure the computer's firewall accordingly.
For example, you can use the Configurator GUI to set up a firewall port. When opening the port in the firewall, you should add a rule that is as strict as possible, to prevent connections from untrusted computers.

caution

The REST API is designed for use in a protected intranet only. It offers no user authentication or other security measures, such as mechanisms against denial-of-service attacks. If this is required, you should implement a web application firewall (WAF).

The Conversion Service supports cross-origin requests (CORS). Cross-origin request are required when sending requests using JavaScript from a browser. By default, requests from all origins are allowed. If necessary, you can restrict cross-origin requests to certain origins using the service's configuration.

Perform API calls​

The API supports XML and JSON format in the request and response body.

In the event of an error, the API returns a HTTP status code and a problem details object (RFC 787). This object contains more information on the type and cause of the error. The object's detail property contains an explanation that helps you to troubleshoot the issue. Therefore, you should parse and use the problem details object (application/problem+xml or application/problem+json) whenever the returned HTTP status code indicates an error.

tip

Set the Content-Type and Accept parameters in the header to your preferred type.

You can find detailed information about the endpoints provided by the API in the API reference. The API reference is also available as an OpenAPI YAML file inside the installation directory. You can view the YAML file in an OpenAPI editor or use it to generate client stub code for any programming language.

Try out the API in Postman

Pdftools lets you generate API requests for all our endpoints via our Postman collection. Postman is a free-to-use visual editing tool for building and testing APIs. Postman lets you easily edit API requests, view header information, and much more.

  1. Save the Conversion Service Postman collection as a JSON file.
  2. Open the Postman API Client, select the Collections view, and click Import.
  3. Drag the downloaded collection JSON file to the Import window.
  4. Click on 4-Heights® Conversion Service in the Collections view.
Using the Conversion Service collection
When you use the Conversion Service Postman collection for the first time. here's the steps to proceed:

1. Specify the base URL: Ensure the baseURL in your collection variables specifies the host where your Conversion Service runs.
2. Get a list of the available workflows: Try out a simple request such as a list of the available workflows. This will help give you an overview of the available workflows in the Conversion Service, so you can then use one as an input parameter when you create a new job.
3. Process a file: Process your first file, bearing in mind the job processing sequence.

Error codes​

If an error occurs during processing in a workflow, an error code with an explanatory message is returned. The following are common error codes:

  • Internal: The Conversion Service is not operational because of an internal issue, e.g. an incomplete installation. A detailed description of the problem is written to the service log file with Error severity level.
    The service administrator should be notified of the problem and submit a support request. No specific error message is return because the issue is not related to the client or the request. This behavior can be changed in the service configuration. However, since the error is related to the service's configuration and the detailed description is designed to help the administrator resolve the problem quickly, the message might reveal internal configuration settings that you may not want to disclose to clients. Therefore, this is generally only recommended during installation and testing of the Conversion Service.
  • External: An error occurred while trying to use an external service or load a required external resource.
  • Configuration: The Conversion Service is not operational because of a configuration issue, e.g. an invalid or an incompatible setting. A detailed description of the problem is written to the service log file with Error severity level.
    The service administrator should resolve the problem with the help of the Configurator.
  • Generic: A generic error occurred.
  • UnsupportedFormat: The format of the input data is not supported.
  • UnsupportedFeature: An unsupported feature was requested. This may be a feature of the input data or one requested using options.
  • Option: An error occurred that is related to job or document options passed by the client.
    For example:
    • A required option is missing.
    • An option has an invalid or unsupported value.
  • Canceled: The job has been canceled by the user.
  • Timeout: The job has been canceled because of a processing timeout.
  • Password: The data cannot be processed because of a missing or invalid password. Retry the conversion and specify the missing password using the document option DOC.PASSWORD.
    This option can be added multiple times to try several passwords for a document or to specify passwords for multiple files, e.g. attachments or embedded files.
  • Conformance: There is a problem with the conformance of the input data.
    For example:
    • The input data's conformance is not supported.
    • The input data cannot be converted to meet the conformance required by the workflow and profile.
  • Corrupt: Data cannot be processed because it is corrupt.

Process conversion jobs​

For a general overview of how jobs are processed by the Conversion Service, see how the Conversion Services works or the specific workflows such as PDF/A 2 or Conversion workflows.

To schedule a job and retrieve its result, the sequence is as follows:

Job processing sequence

There is no limit of the number of jobs that can be started concurrently. The service processes the jobs in the order they were created, using the highest concurrency allowed by the system's CPU and the license.

Nonetheless, it is recommended to not start much more jobs than the service can process. For example, on a machine with 8 CPU cores and a license for 8 cores, not much more than 8 jobs should be started. To determine the maximum concurrency, the whole system and configuration must be taken into consideration. Dependent systems such as an OCR service or Office conversion may further limit the maximum concurrency.

Get service information​

These methods return information regarding the service's overall status:

  • getServiceStatus
  • listJobs
  • listWorkflows

Get service status​

The getServiceStatus method can be used to retrieve general status information. You can use this method to verify if the service is running, to monitor service health. In addition, you can get information on the service's load and general job count.

For more information, see Get the Service Status endpoint.

Get a list of jobs​

The listJobs method returns a list of all jobs and their status. You can use this method to see what tasks are currently executing.

For more information, see List all jobs endpoint.

Get a list of all workflows​

The listWorkflows method returns a list of all workflows and their profiles.

For more information, see List all workflows endpoint.