Skip to main content

REST input (Simple API)

The REST input connectors convert files sent in API requests. These connectors are also called the Conversion Service Simple API. Compared to the Advanced API, the Simple API returns converted files in just one API call.

This documentation specific aspects of the Simple API in depth. If you need a tutorial or references, refer to:

Predefined connectors​

The Conversion Service provides a set of predefined connectors that leverage the Simple API:

  • REST API Archive PDF/A-2
  • REST API Archive PDF/A-3
  • REST API All to PDF Profile
  • REST API Merge Profile
  • REST API Ready to Print PDF/A-2
  • REST API Ready for Web PDF/A-2
  • REST API Ready for Email PDF/A-2
  • REST API Repair Profile

When the Conversion Service is running locally or on an IP address that you specify in the baseURL, you can test these connectors using the Simple API Postman collection or the Simple API reference.

Note that in the Conversion Service Configurator, all of these connectors include REST API in their name. However, this REST API wording is not included in the API references or in the Postman collection. For example: Archive PDF/A-2 in the Postman collection or API references is REST API Archive PDF/A-2 in the Conversion Service Configurator.

Custom REST connectors​

Choose your own workflow and profile in the Conversion Service Configurator Integrations tab. You can create your custom REST connectors that leverage Simple API with specific requirements that you set up.

info

To get started with your custom connector, review in the Simple API getting started guide. Create custom connection.

All of these connectors can use one of the following methods (the methods are also called connectors):

REST input plain HTTP​

The REST Input connector sends files as single or multiple files in the request body. The connector then returns the response of whether the files were accepted or retrieves the result files.

Request​

The connector can handle the following two request formats:

  • Multiple files: Send as multipart/form-data body. All files are merged into the same job.
  • Single file: Send as a raw request body. Set the filename URL query parameter in the URL to specify the name of the file. Otherwise, a default name is used.

Options and variables​

Customize options and variables to either change the processing of the files in the workflow itself or in the output connector.

  • Options: Customize document processing with job and document options. Available options vary depending on the workflow you select. Options customize the processing of the documents in the workflow itself. For more information, see Job and document options documentation.
  • Variables: Use variables to pass through information to the output connector. The format of the variables is: [input:VARIABLE_NAME]. Use these variables, for example, in the output connectors such as:

Both Options and Variables support placeholder syntax. Conversion Service supports query parameters and form data extraction. Query parameters are supported with the placeholder syntax for both request formats. Note that the form request format is not available for the single file:

  • [query:QUERY-PARAM-NAME, 'DEFAULT-VALUE']
  • [form:FORM-DATA-NAME, 'DEFAULT-VALUE']
Configuration window of REST Input (HTTP Plain).

Response​

The connector can be configured to provide one of the following three different response types:

  • The call returns with an HTTP status 202 Accepted immediately. The result is handled exclusively by the configured output connectors.
  • The call blocks until the job has finished and the first result file is returned as response body.
  • The call blocks until the job has finished and all result files are returned as multipart/form-data response.

REST input JSON​

The REST Input connector uses JSON as a structured format for request and response.

Request​

This connector allows to specify a job in a structured format (JSON). The files to be converted can either be referenced by URL or included directly in the job description.

{
  "name": "JOB_NAME",
  "options": [
    { "name": "OPTION_NAME", "value": "OPTION_VALUE" }
  ],
  "variables": {
    "VARIABLE_NAME": "VARIABLE_VALUE"
  },
  "data": [
    // First file referenced by URL
    { "url": "http://example.com/path/to/file.jpg" },
    // Second file inline
    { "fileName": "file.jpg", "content": "BASE64_ENCODED_FILE" },
    // Third file with options
    { "fileName": "file2.jpg", "content": "BASE64_ENCODED_FILE",
      "options": [ { "name": "DOC.PASSWORD", "value": "USE_YOUR_PASSWORD" } ] }
  ]
}

Options and variables​

Customize options and variables to either change the processing of the files in the workflow itself or in the output connector.

  • Options: Customize document processing with job and document options. Available options vary depending on the workflow you select. Options customize the processing of the documents in the workflow itself. For more information, see Job and document options documentation.
  • Variables: Use variables to pass through information to the output connector. The format of the variables is: [input:‹variable name›]. Use these variables, for example, in the output connectors such as:

Response​

The connector can be configured to provide one of the following two different response types:

  • The call returns with an HTTP status 202 Accepted immediately. The result is handled exclusively by the configured output connectors.
  • The call blocks until the job has finished and all result files are returned as a structured JSON response.
{
  "data": [
    { "fileName": "file.pdf", "content": "BASE64_ENCODED_FILE" },
    { "fileName": "report.txt", "content": "BASE64_ENCODED_FILE" }
  ]
}

You can find more details about the Simple API in: