AppSuite:DocumentConverter API - Revision history

Kai.ahrens: Added 'priority' parameter to API description

2019-09-13T12:24:48Z

Added 'priority' parameter to API description

← Older revision		Revision as of 12:24, 13 September 2019
Line 49:		Line 49:
	* firstpageonly: ["false" \| "true"] (Optional, Default: "false")		* firstpageonly: ["false" \| "true"] (Optional, Default: "false")
	* returntype: ["file" \| "json"] (Optional, Default: "file")		* returntype: ["file" \| "json"] (Optional, Default: "file")
			* priority: ["background" \| "low" \| "medium" \| "high" \| "instant"] (Optional, Default: "low")

	:Return Value		:Return Value
Line 63:		Line 64:
	* targetformat: "jpeg" \| "png"		* targetformat: "jpeg" \| "png"
	* returntype: ["file" \| "json"] (Optional, Default: "file")		* returntype: ["file" \| "json"] (Optional, Default: "file")
			* priority: ["background" \| "low" \| "medium" \| "high" \| "instant"] (Optional, Default: "low")

	:Return Value		:Return Value
Line 77:		Line 79:
	* targetformat: "jpeg" \| "png"		* targetformat: "jpeg" \| "png"
	* returntype: [“file” \| “json”] (Optional, Default: “file”)		* returntype: [“file” \| “json”] (Optional, Default: “file”)
			* priority: ["background" \| "low" \| "medium" \| "high" \| "instant"] (Optional, Default: "low")

	:Return Value		:Return Value
Line 90:		Line 93:
	* targetformat: "html" \| "jpeg" \| "png"		* targetformat: "html" \| "jpeg" \| "png"
	* url: dataURL \| fileURL \| httpURL		* url: dataURL \| fileURL \| httpURL
			* priority: ["background" \| "low" \| "medium" \| "high" \| "instant"] (Optional, Default: "low")

	:Return Value		:Return Value

Stx12: /* getpreview */

2013-02-07T15:35:26Z

getpreview

← Older revision		Revision as of 15:35, 7 February 2013
Line 59:		Line 59:

	:Call Parameters		:Call Parameters
	* action: "~~getthumbnail~~"		* action: "getpreview"
	* url: dataURL \| fileURL \| httpURL		* url: dataURL \| fileURL \| httpURL
	* targetformat: "jpeg" \| "png"		* targetformat: "jpeg" \| "png"

Stx12: link to entry page for converter

2013-02-07T11:25:35Z

link to entry page for converter

← Older revision		Revision as of 11:25, 7 February 2013
Line 4:		Line 4:

	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.		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 ~~this~~ 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.		The sole purpose of the [[AppSuite:DocumentConverter_Installation_Guide\|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.		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.

Stx12: add section sample code

2013-02-06T16:54:01Z

add section sample code

← Older revision		Revision as of 16:54, 6 February 2013
Line 117:		Line 117:
	:Return Value		:Return Value
	* json {errorcode: "errorCode"}		* json {errorcode: "errorCode"}

			== Sample Code ==

			A small example shows the usage of the API.
			Adapt the [[Media:DocumentConverterSample.java\|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.

Stx12: some nowiki

2013-02-06T13:05:15Z

some nowiki

← Older revision		Revision as of 13:05, 6 February 2013
Line 8:		Line 8:
	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.		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 ====		=== Base URL ===
	The base URL to initiate a conversion is as follows:		The base URL to initiate a conversion is as follows:
	%%http://host:port/documentconverterws ~~%%//~~		http://host:port/documentconverterws

	=== Parameters ===		=== Parameters ===

Stx12: added overview

2013-02-06T12:58:16Z

added overview

← Older revision		Revision as of 12:58, 6 February 2013
Line 1:		Line 1:
	== OX Document Converter API ==		== OX Document Converter 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 this 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.		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.

Stx12: adjusting indents

2013-02-06T12:03:14Z

adjusting indents

← Older revision		Revision as of 12:03, 6 February 2013
Line 18:		Line 18:
	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.		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		:Call Parameters
	* action: "convert"		* action: "convert"
	* url: dataURL \| fileURL \| httpURL		* url: dataURL \| fileURL \| httpURL
Line 25:		Line 25:
	* returntype: ["file" \| "json"] (Optional, Default: "file")		* returntype: ["file" \| "json"] (Optional, Default: "file")

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

Line 33:		Line 33:
	The result as a file or as the dataURL of the JSON response is given back in the native format of the 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 :		:Call Parameters
	* action: "getthumbnail"		* action: "getthumbnail"
	* url: dataURL \| fileURL \| httpURL		* url: dataURL \| fileURL \| httpURL
Line 39:		Line 39:
	* returntype: ["file" \| "json"] (Optional, Default: "file")		* returntype: ["file" \| "json"] (Optional, Default: "file")

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

Line 47:		Line 47:
	The result as a file or as the dataURL of the JSON response is given back in the native format of the 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 ~~====~~		:Call Parameters
	* action: "getthumbnail"		* action: "getthumbnail"
	* url: dataURL \| fileURL \| httpURL		* url: dataURL \| fileURL \| httpURL
Line 53:		Line 53:
	* returntype: [“file” \| “json”] (Optional, Default: “file”)		* returntype: [“file” \| “json”] (Optional, Default: “file”)

	~~====~~ Return Value ~~====~~		:Return Value
	* file \| json {errorcode: “errorCode”, mimetype: “mimeType”, extension: “extension”, result: “dataURL”}		* file \| json {errorcode: “errorCode”, mimetype: “mimeType”, extension: “extension”, result: “dataURL”}

Line 61:		Line 61:
	The result is returned in JSON format.		The result is returned in JSON format.

	~~===~~ Call Parameters ~~===~~		:Call Parameters
	* action: "beginconvert"		* action: "beginconvert"
	* targetformat: "html" \| "jpeg" \| "png"		* targetformat: "html" \| "jpeg" \| "png"
	* url: dataURL \| fileURL \| httpURL		* url: dataURL \| fileURL \| httpURL

	~~===~~ Return Value ~~===~~		:Return Value
	* json {errorcode: "errorCode", jobid: "jobId", pagecount: "pageCount"}		* json {errorcode: "errorCode", jobid: "jobId", pagecount: "pageCount"}

	==== getpage ====		=== 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'.		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.		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 ~~===~~		:Call Parameters
	* action: "getpage"		* action: "getpage"
	* jobid: jobID		* jobid: jobID
Line 80:		Line 80:
	* returntype: [“file” \| “json”] (Optional, Default: “file”)		* returntype: [“file” \| “json”] (Optional, Default: “file”)

	~~===~~ Return Value ~~===~~		:Return Value
	* file \| json {errorcode: “errorCode”, mimetype: “mimeType”, extension: “extension”, result: “dataURL”}		* file \| json {errorcode: “errorCode”, mimetype: “mimeType”, extension: “extension”, result: “dataURL”}

	==== endconvert ====		=== 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.		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 ~~===~~		:Call Parameters:
	* action: "endconvert"		* action: "endconvert"
	* jobid: jobID		* jobid: jobID

	~~===~~ Return Value ~~===~~		:Return Value
	* json {errorcode: "errorCode"}		* json {errorcode: "errorCode"}

Stx12: playing with indents

2013-02-06T11:50:06Z

playing with indents

← Older revision		Revision as of 11:50, 6 February 2013
Line 18:		Line 18:
	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.		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 ~~====~~		; Call Parameters
	* action: "convert"		* action: "convert"
	* url: dataURL \| fileURL \| httpURL		* url: dataURL \| fileURL \| httpURL
Line 25:		Line 25:
	* returntype: ["file" \| "json"] (Optional, Default: "file")		* returntype: ["file" \| "json"] (Optional, Default: "file")

	~~====~~ Return Value ~~====~~		; Return Value
	* file \| json {errorcode: "errorCode", mimetype: "mimeType", extension: "extension", result: "dataURL"}		* file \| json {errorcode: "errorCode", mimetype: "mimeType", extension: "extension", result: "dataURL"}

Line 33:		Line 33:
	The result as a file or as the dataURL of the JSON response is given back in the native format of the 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 ~~====~~		; Call Parameters :
	* action: "getthumbnail"		* action: "getthumbnail"
	* url: dataURL \| fileURL \| httpURL		* url: dataURL \| fileURL \| httpURL
Line 39:		Line 39:
	* returntype: ["file" \| "json"] (Optional, Default: "file")		* returntype: ["file" \| "json"] (Optional, Default: "file")

	~~====~~ Return Value ~~====~~		; Return Value :
	* file \| json {errorcode: “errorCode”, mimetype: “mimeType”, extension: “extension”, result: “dataURL”}		* file \| json {errorcode: “errorCode”, mimetype: “mimeType”, extension: “extension”, result: “dataURL”}

Stx12: adjustments of headings

2013-02-06T11:19:23Z

adjustments of headings

New page

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