AppSuite:DocumentConverter API

Overview

Beside the primary implementation design goals of stability and robustness, one of the API design goals was ease of use, combined with a reasonable, but easily extensible feature set. The sole purpose of the OX Document Converter web service is to offer conversion functionality of a wide range of commonly available, often proprietary, document formats into well known standards, that can be displayed and post processed by standard tools like web browsers, image tools or pdf viewers.

Having this single purpose as its main feature, the API of this web service indeed consists of one call, receiving the data of an arbitrary input document and returning the result of the conversion in another format, that the user can specify.

Base URL

The base URL to initiate a conversion is as follows:

http://host:port/documentconverterws

Parameters

To initiate a conversion via the OX Document Converter WebService, an XMLHttpRequest object is created on client side, containig the basic URL as given above and setting the following parameters at the request:

 * 'action':  the action to be performed; currently, only 'convert' is supported
 * 'fileformat': the file format of the conversion result; currently supported file fomats are:
   * 'html': the result is returned as a HTML document, containing SVG elements for each page of the converted  document
   * 'pdf': the result is returned as a PDF document
 * 'data'; the Base64 encoded file content to be converted

The XMLHttpRequest has to be executed as a POST request. As such, the parameters of the request need to be set within the body of the request. The data parameter contains the content of the source document to be converted. It needs to be encoded as Base64 data. The result of the conversion can be obtained from the HTTP response.

Reference

The Open-Xchange DocumentConverter WebService API consists of a set of possible HTTP requests, with each different call defined by a set of HTTP request parameters.

If not stated otherwise, the listed parameters for each call are mandatory. A set of possible parameter values for a call parameter is denoted by a pipe symbol within this documentation. Parameter values in quotes are fixed values. The quote character itself must not be set within the real call. Parameter values without quotes are placeholders for user defined values

URLs within the call can be either specified as a data URL, a HTTP URL or a file URL. In the case of data URLs, the caller needs to take care of using only the POST method for making the HTTP request in order to allow the upload of large data. Some possible example URLs are given below:

 data:mimeType;base64,dataSequence (HTTPRequest via POST method only)
 http://www.example.com/test.odf (HTTPRequest via GET or POST method)
 file:///home/example/test.odf (HTTPRequest via GET or POST method)

Return values are either file attachments or objects according to the JSON notation within the response body of the HTTP request. Depending on the chosen/available return type of the call, the receiver of the call needs to handle this return value accordingly.

convert

Stateless conversion of a file, specified by an URL, to a target format.

The conversion result data is given back as an archive in the file case as well as in the JSON case.\\ In the JSON case, the returned mime type parameter contains the mime type of the single pages within the returned archive.\\ The extension parameter contains the default file extension for the returned mime type for convenience reasons at further processing steps within the client code.

Call Parameters

 * action: "convert"
 * url: dataURL | fileURL | httpURL
 * targetformat: "html" | "pdf" | "odf" | "ooxml" | "jpeg" | "png"
 * firstpageonly: ["false" | "true"] (Optional, Default: "false")
 * returntype: ["file" | "json"] (Optional, Default: "file")
 * priority: ["background" | "low" | "medium" | "high" | "instant"] (Optional, Default: "low")

Return Value

 * file | json {errorcode: "errorCode", mimetype: "mimeType", extension: "extension", result: "dataURL"}

getpreview

Stateless retrieval of a preview from a file, specified by an URL, as an image.

The result as a file or as the dataURL of the JSON response is given back in the native format of the image.

Call Parameters

 * action: "getpreview"
 * url: dataURL | fileURL | httpURL
 * targetformat: "jpeg" | "png"
 * returntype: ["file" | "json"] (Optional, Default: "file")
 * priority: ["background" | "low" | "medium" | "high" | "instant"] (Optional, Default: "low")

Return Value

 * file | json {errorcode: “errorCode”, mimetype: “mimeType”, extension: “extension”, result: “dataURL”}

getthumbnail

Stateless retrieval of a thumbnail preview from a file, specified by an URL, as an image.

The result as a file or as the dataURL of the JSON response is given back in the native format of the image.

Call Parameters

 * action: "getthumbnail"
 * url: dataURL | fileURL | httpURL
 * targetformat: "jpeg" | "png"
 * returntype: [“file” | “json”] (Optional, Default: “file”)
 * priority: ["background" | "low" | "medium" | "high" | "instant"] (Optional, Default: "low")

Return Value

 * file | json {errorcode: “errorCode”, mimetype: “mimeType”, extension: “extension”, result: “dataURL”}

beginconvert

Initiating a stateful/cached conversion of a file, specified by an URL, to a target format. The result object contains the jobId to work with in subsequent calls to "getpage" and "endconvert".

The result is returned in JSON format.

Call Parameters

 * action: "beginconvert"
 * targetformat: "html" | "jpeg" | "png"
 * url: dataURL | fileURL | httpURL
 * priority: ["background" | "low" | "medium" | "high" | "instant"] (Optional, Default: "low")

Return Value

 *  json {errorcode: "errorCode", jobid: "jobId", pagecount: "pageCount"}

getpage

Stateful call to retrieve a specified page from a previously initiated conversion job. 'beginconvert' must have been called before in order to acquire the correct 'jobid'.

The result as a file or as the dataURL of the JSON response is given back in the native format of the converted page.

Call Parameters

 * action: "getpage"
 * jobid: jobID
 * pagenumber: pageNumber
 * returntype: [“file” | “json”] (Optional, Default: “file”)

Return Value

 * file | json {errorcode: “errorCode”, mimetype: “mimeType”, extension: “extension”, result: “dataURL”}

endconvert

Finishing a previously initiated conversion job. This call needs to be made in order to free any cached resources, that have been allocated since the 'beginconvert' call. The initially returned jobId is not valid after this call anymore.

Call Parameters:

 * action: "endconvert"
 * jobid: jobID

Return Value

 * json {errorcode: "errorCode"}

Sample Code

A small example shows the usage of the API. Adapt the sample code to match your installation. There are two occurrences of host.example.com with have to replaced with the server running the conversion service.