Skip to main content

REST API connectors

The REST input and output connectors convert all files that are sent and returned to a URL. The URL is customizable by configuring the connection ID.

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 a 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": "mypassword" } ] }
  ]
}

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 a 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›" }
  ]
}

REST Output​

The REST Output connector posts files as a multipart/form-data request to a configurable output URL. The URL may contain placeholder variables coming from the input connector.

For example:

  • http://example.com/path/on/server/?id=[input:id]
  • [input:url]
  • http://example.com/[input:serverpath]

The following additional configuration options are available:

  • The connector can either post the unchanged input files or the converted result files.
  • The form-data field name of the files.
  • Additional form fields can be configured where the values may contain placeholder values coming from the input connector.
  • The value of the HTTP Accept header can be configured freely.

Authentication​

The connector supports username/password based authentication schemes such as Basic, Digest, NTLM, and Kerberos.

The server must challenge unauthenticated requests properly with a 401 response. The connector preauthenticates subsequent requests to the same URL, i.e. send the necessary HTTP header without waiting to be challenged by the server.