Chapter 8. API (non-interactive requests) Previous topic Parent topic Child topic Next topic

The API of XMLmind XSL Server consists in just 5 requests. These requests may be sent to the server using either HTTP GET or HTTP POST application/x-www-form-urlencoded.

Request xslsrv/exec?op=convert

Description:
Create a new job allowing to convert specified XML document to another format using specified conversion specification.
If a similar job (same url, html, conv, paramI/valueI, out parameters) already exists, no new job is created and the existing job is returned instead.
Parameters other than op:
Name Value Default value Description
mode async | sync | interactive interactive
Mode=async or mode=sync must be specified, otherwise this request returns an interactive Convert form.
The difference between the two modes is explained below.
conv The name of a conversion specification. Required.
Specifies which conversion is to be applied to the input document.
Tip
Tip
Invoke xslsrv/exec?op=config to list all the available conversion specifications.
paramI (I between 0 and 99) Non-empty string. None Pass these extra parameters to the XSLT stylesheets referenced by the conversion specification.
valueI String. None Value of XSLTstylesheet parameter paramI.
url URL One of url and file0 is required. URL of the input document.
fileI (I between 0 and 99)
Uploaded file.
One of url and file0 is required.
Attention
Attention
When fileI parameters are used, the request must be sent using HTTP POST multipart/form-data.
The input document is contained in file0. Attachments (e.g. graphic files) are contained in fileI, where I is an integer between 1 and 99.
Alternatively, all the files may be packed in a Zip archive. However this must be done exactly like in the following example.
Let's suppose you want to convert userguide.fo to RTF and userguide.fo references several graphic files found in subdirectory std/. You'll have to create userguide.fo.zip as follows:
~/tmp$ ls
sdt
userguide.fo

~/tmp$ ls sdt
drop-down-list-1.png
drop-down-list-2.png
...

~/tmp$ zip -r userguide.fo.zip \
    userguide.fo sdt
~/tmp$ ls
sdt
userguide.fo
userguide.fo.zip
  • The Zip archive must be named after the XML document to be converted. That is, append ".zip" to the basename of the XML document to be converted.
  • The Zip archive must directly contain the XML document to be converted. Subdirectories are allowed only for the referenced files.
html true | false false The input document must be parsed as HTML, and not as XML or XHTML (XHTML is a special kind of XML).
out String
Same basename as the input file but with the extension specified in the conversion specification (e.g. ".pdf" for db5ToPDF).
If the conversion specification generates a directory (e.g. ditaToXHTML), the contents of this directory is packed in a Zip archive having the same basename of the input file but with a ".zip" extension.
The basename of the result file.
cache true | false
  • true, if the input document has been specified by its URL.
  • false, if the input document has been uploaded.
If true, cache the result of this job.
Note that only the result of converting an URL can be cached. The result of converting an uploaded file cannot be cached.
auth String.
None.
Required and equal to authorization1_token if the authorization1 server parameter has been specified.
Authorization token specified for conversion operations.
Response:
  • If mode=async, plain/text;charset=UTF-8 containing the ID of the job. This job is intended to be polled using xslsrv/exec?op=poll.
  • If mode=sync,
    • If the job has successfully been executed, the file which is the result of the job.
    • Otherwise, a plain/text;charset=UTF-8 file containing its progress log. This file has the following format.
Examples: Requires cURL Opens in new window, a command-line tool for transferring data using various protocols. (In the examples below, long lines have been folded. In reality, this is not the case.)
$ curl 'http://localhost:8080/xslsrv/exec?op=convert&mode=async¬
&conv=xhtmlToPDF&param0=root-id&value0=contents-box¬
&out=xfc.pdf¬
&html=true&url=http://www.xmlmind.com/foconverter/what_is_xfc.html'
7

$ curl -o xfc.pdf 'http://localhost:8080/xslsrv/exec/xfc.pdf?op=result&job=7'

$ acroread xfc.pdf &

$curl -o tutorial.zip 'http://localhost:8080/xslsrv/exec?op=convert&mode=sync¬
&conv=ditaToXHTML¬
&url=http://www.xmlmind.com/tutorials/DITA/src/tutorial.ditamap'

$ unzip -v tutorial.zip

Request xslsrv/exec?op=poll

Description:
If specified job has successfully been executed, download its result file, otherwise download a plain text file containing its progress log.
Parameters other than op:
Name Value Default value Description
job Integer larger than or equal to 0. Required. The ID of the job which is to be polled.
from Integer 0.
If specified job has successfully been executed, this parameter is ignored.
Otherwise this parameter specifies the index of the first progress message that should appear in the downloaded log file. The first index is 0.
A negative index means: return the end of the log file, that is, count messages starting from the end of the log file rather than from its beginning.
auth String.
None.
Required and equal to authorization1_token if the authorization1 server parameter has been specified.
Authorization token specified for conversion operations.
Response:
If specified job has successfully been executed, the file which is the result of the job. Otherwise a plain/text;charset=UTF-8 log file having this format:
file -> job_status 
        '\n' index_of_first_message 
        '\n' message_count 
        [ '\n' message ]*

job_status -> CREATED|RUNNING|CANCELED|FAILED|DONE|CANCELING|CRASHED

index_of_first_message -> Positive_Integer

message_count -> Positive_Integer

message -> start_message | 
           step_count_message | 
           step_message | 
           progress_message | 
           stop_message

start_message -> START ' ' -

step_count_message -> STEP_COUNT ' ' -1|Positive_Integer

step_message -> STEP ' ' Positive_Integer

progress_message -> MESSAGE ' ' ERROR|WARNING|INFO|VERBOSE|DEBUG ': ' Text_Line

stop_message -> STOP ' ' -
  • The very first message of the progress log is guaranteed to be start_message.
  • Step_count_message is guaranteed to occur before step_message (if any step_message).
  • STEP_COUNT -1 means: undetermined number of steps.
  • In progress_message, the backslash character is escaped as "\\" and the newline character is escaped as "\n".
  • The very last message of the progress log is guaranteed to be stop_message.
Examples: (In the examples below, long lines have been folded. In reality, this is not the case.)
$ curl -o 'http://localhost:8080/xslsrv/exec?op=poll&job=12345'
UNKNOWN
0
0

$ curl -o 'http://localhost:8080/xslsrv/exec?op=poll&job=5'
RUNNING
0
9
START -
STEP_COUNT 4
STEP 0
MESSAGE INFO: Converting¬
"http://www.xmlmind.com/xmleditor/_distrib/demo/docbook-image.xml"¬
to "/opt/tomcat2/work/Catalina/localhost/xslsrv/cache/6/docbook-image.pdf"¬
using conversion specification "dbToPDF"...
STEP 1
MESSAGE INFO: Compiling XSLT stylesheet¬
"/opt/tomcat2/webapps/xslsrv/addon/config/docbook/xsl/fo/docbook.xsl"...¬
MESSAGE INFO: XSLT stylesheet compiled in 0.0s.
STEP 2
MESSAGE INFO: Transforming¬
"http://www.xmlmind.com/xmleditor/_distrib/doc/user/docbook-image.xml"¬ 
to "/opt/tomcat2/work/Catalina/localhost/xslsrv/tmp/xslu8379/xslu5120.tmp"¬ 
using XSLT stylesheet¬
"/opt/tomcat2/webapps/xslsrv/addon/config/docbook/xsl/fo/docbook.xsl"...

$ curl -o 'http://localhost:8080/xslsrv/exec?op=poll&job=5&from=-3'
STEP 3 
MESSAGE INFO: Converting 
"/opt/tomcat2/work/Catalina/localhost/xslsrv/tmp/xslu8379/xslu5120.tmp"¬ 
to "/opt/tomcat2/work/Catalina/localhost/xslsrv/cache/6/docbook-image.pdf"¬ 
using XSL-FO processor "FOP"...
MESSAGE WARNING: [FOP WARNING] Font 'Symbol,normal,700' not found.¬
Substituting with 'Symbol,normal,400'.

Request xslsrv/exec?op=cancel

Description:
Cancel the execution of specified job. The execution of a job can be canceled only when this job is in the Running state.
Parameters other than op:
Name Value Default value Description
job Integer larger than or equal to 0. Required. The ID of the job whose execution is to be canceled.
auth String.
None.
Required and equal to authorization1_token if the authorization1 server parameter has been specified.
Authorization token specified for conversion operations.
Response:
Plain/text;charset=UTF-8 containing true if the job has successfully been switched from the Running to the Canceling state or is already in the Canceling state; false otherwise.
Examples:
$ curl -'http://localhost:8080/xslsrv/exec?op=cancel&job=4'
true

$ curl -'http://localhost:8080/xslsrv/exec?op=cancel&job=4'
true

$ curl -'http://localhost:8080/xslsrv/exec?op=cancel&job=4'
false

Request xslsrv/exec?op=result

Description:
Download the result of specified job.
Important
Important
As a simple security check, the basename of the file which is the result of the job must be passed in the request URL just after xslsrv/exec. See examples below.
Parameters other than op:
Name Value Default value Description
job Integer larger than or equal to 0. Required. The ID of the job whose result is to be downloaded.
auth String.
None.
Required and equal to authorization1_token if the authorization1 server parameter has been specified.
Authorization token specified for conversion operations.
Response:
The file which is the result of the job. If, for any reason, this file does not exist, returns HTTP error "404, Not Found".
Examples:
$ curl -o docbook-table.pdf \
'http://localhost:8080/xslsrv/exec/docbook-table.pdf?op=result&job=1'

$ acroread docbook-table.pdf &

$ curl -o dita-sample.zip \
'http://localhost:8080/xslsrv/exec/dita-sample.zip?op=result&job=3'

$ unzip -v dita-sample.zip

$curl 'http://localhost:8080/xslsrv/exec/foo.bar?op=result&job=1234'
HTTP Status 404 - the output of job #1234 is not available

Request xslsrv/exec?op=clear

Description:
Discard the result of specified job.
Note that the result of a job cannot be discarded in the following cases:
  • Specified job ID is unknown or is no longer known.
  • It is too early to discard the result of specified job. See the keepTimeWhenDone and keepTimeWhenFailed server parameters.
Parameters other than op:
Name Value Default value Description
job Integer larger than or equal to -1. Required. The ID of the job whose result is to be discarded. -1 means: all jobs.
auth String.
None.
Required and equal to authorization2_token if the authorization2 server parameter has been specified.
Authorization token specified for administrative operations.
Response:
Plain/text;charset=UTF-8 containing the number of job results which have been discarded.
Examples:
~$ curl 'http://localhost:8080/xslsrv/exec?op=clear&job=12'
0

~$ curl 'http://localhost:8080/xslsrv/exec?op=clear&job=-1'
2