AppSuite:DocumentConverter API

OX Document Converter API

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")

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: "getthumbnail"
 * url: dataURL | fileURL | httpURL
 * targetformat: "jpeg" | "png"
 * returntype: ["file" | "json"] (Optional, Default: "file")

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”)

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

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"}