Initiating Jobs with POST
This section:
•JSON syntax for POST requests
•Uploading files with the POST request
Sending the request
A RaptorXML+XBRL Server job is initiated with the HTTP POST method
HTTP Method | URI | Content-Type | Body |
POST | http://localhost:8087/v1/queue/ | application/json | JSON |
Note the following points:
•The URI above has a server address that uses the settings of the initial configuration.
•The URI has a /v1/queue/ path, which must be present in the URI. It can be considered to be an abstract folder in memory into which the job is placed.
•The correct version number /vN is the one that the server returns (and not necessarily the one in this documentation). The number that the server returns is the version number of the current HTTP interface. Previous version numbers indicate older versions of the HTTP interface, which are still supported for backward compatibility.
•The header must contain the field: Content-Type: application/json. However, if you wish to upload files within the body of the POST request, then the message header must have its content type set to multipart/form-data (i.e. Content-Type: multipart/form-data). See the section Uploading files with the POST request for details.
•The body of the request must be in JSON format.
•Files to be processed must be on the server. So files must either be copied to the server before a request is made, or be uploaded along with the POST request. In this case the message header must have its content type set to multipart/form-data. See the section Uploading files with the POST request below for details.
To check the well-formedness of an XML file, the request in JSON format would look something like this:
{
"command": "wfxml", "args": [ "file:///c:/Test/Report.xml" ]
}
Valid commands, and their arguments and options, are as documented in the Command Line section.
JSON syntax for HTTP POST requests
{ "command": "Command-Name", "options": {"opt1": "opt1-value", "opt2": "opt2-value"}, "args" : ["file:///c:/filename1", "file:///c:/filename2"] }
•All black text is fixed and must be included. This includes all braces, double quotes, colons, commas, and square brackets. Whitespace can be normalized.
•Blue italics are placeholders and stand for command names, options and option values, and argument values. Refer to the command line section for a description of the commands.
•The command and args keys are mandatory. The options key is optional. Some options keys have default values; so, of these options, only those for which the default values need to be changed need be specified.
•All strings must be enclosed in double quotes. Boolean values and numbers must not have quotes. So: {"error-limit": "unlimited"} and {"error-limit": 1} is correct usage.
•Notice that file URIs—rather than file paths—are recommended and that they use forward slashes. Windows file paths, if used, take backslashes. Furthermore, Windows file-path backslashes must be escaped in JSON (with backslash escapes; so "c:\\dir\\filename"). Note that file URIs and file paths are strings and, therefore, must be in quotes. |
Here is an example with options. Notice that some options (like input or xslt-version) take a straight option value, while others (like param) take a key-value pair as their value, and therefore require a different syntax.
{
"command": "xslt",
"args": [
"file:///C:/Work/Test.xslt"
],
"options": {
"input": "file:///C:/Work/Test.xml",
"xslt-version": "1",
"param": {
"key": "myTestParam",
"value": "SomeParamValue"
},
"output": "file:///C:/temp/out2.xml"
}
}
The example below shows a third type of option: that of an array of values (as for the xsd option below). In this case, the syntax to be used is that of a JSON Array.
{
"command": "xsi",
"args": [
"file:///C:/Work/Test.xml"
],
"options": {
"xsd" : ["file:///C:/Work/File1.xsd", "file:///C:/Work/File2.xsd"]
}
}
Uploading files with the POST request
Files to be processed can be uploaded within the body of the POST request. In this case, the POST request must be made as follows.
Request header
In the request header, set Content-Type: multipart/form-data and specify any arbitrary string as the boundary. Here is an example header:
Content-Type: multipart/form-data; boundary=---PartBoundary
The purpose of the boundary is to set the boundaries of the different form-data parts in the request body (see below).
Request body: Message part
The body of the request has the following form-data parts, separated by the boundary string specified in the request header (see above):
•Mandatory form-data parts: msg, which specifies the processing action requested, and args, which contains the files to be uploaded as the argument/s of the command specified in the msg form-data part. See the listing below.
•Optional form-data part: A form-data part name additional-files, which contains files referenced from files in the msg or args form-data parts. Additionally form-data parts named after an option of the command can also contain files to be uploaded.
Note: All uploaded files are created in a single virtual directory.
See Example-1 (with Callouts): Validate XML for a detailed explanation of the code, and Example-2: Using a Catalog to Find the Schema.
Testing with CURLYou can use a third-party data-transfer application such as CURL (http://curl.haxx.se/) to test the POST request. CURL provides a helpful trace option that generates and lists the part boundaries of the requests. This will save you the task of manually creating the part boundaries. How you can use CURL is described in the section, Testing with CURL.
|
Uploading ZIP archives
ZIP archives can also be uploaded, and files within a ZIP can be referenced by using the additional-files scheme. For example:
additional-files:///mybigarchive.zip%7Czip/biginstance.xml
| Note: | The |zip/ part needs to be URI-escaped as %7Czip/ in order to conform to the URI RFC since the pipe | symbol is not directly allowed. The use of glob patterns (* and ?) is also allowed. So you can use something like this to validate all XML files within the ZIP archive: {"command": "xsi", "args": ["additional-files:///mybigarchive.zip%7Czip/*.xml"], "options": {...}} |
See Example-3: Using ZIP Archives for a listing of example code.