REST I/O Types

Various protocol types are available for use with:

inputA
inputB
output
catalog

See this table for information on the availability of each I/O Type

I/O

HTTP

File (Paths, Objects, XML Strings)

Cloud

inputA

inputB

output

catalog

HTTP

HTTP or HTTPS URIs can be specified and the conversion checker will try to load the specified file.

multipart/form-data

To use HTTP I/O with multipart/form-data, set the Content-Type to text/plain:

CODE

.....
Content-Disposition: form-data; name="inputA"; Content-Type: text/plain;
http://www.example.com/file1.xml
--boundary

In XML this is represented by setting the type attribute on the I/O element to http. The uri child element is then used to set the HTTP or HTTPS URI.

CODE

<inputA type="http">
  <uri>https://www.example.com/file1.xml</uri>
</input>

In JSON this is represented by setting the type key to http. The uri key is then used to set the HTTP or HTTPS URI.

JSON

{
 "inputA": {
   "type": "http",
   "uri": "https://www.example.com/file1.xml"
 }
}

Authorization

If you need to specify an Authorization header to access the content from the resource, you can use the optional authorizationHeader parameter on the inputA/inputB object:

XML

CODE

<inputA type="http">
  <uri>http://www.example.com/file1.xml</uri>
  <authorizationHeader>Basic dGVzdyOnNlY3JldA==</authorizationHeader>
</input>

JSON

{
 "inputA": {
   "type": "http",
   "uri": "http://www.example.com/file1.xml",
   "authorizationHeader": "Basic dGVzdyOnNlY3JldA=="
 }
}

File Paths

This type of I/O is only appropriate when the REST service is being run 'on-premise'. For cloud SaaS use-cases please choose an alternative I/O method.

A file path (on the server) can also be used to specify the input, output, and catalog locations. For example:

multipart/form-data

To use File I/O with multipart/form-data, set the Content-Type to text/plain:

CODE

.....
Content-Disposition: form-data; name="inputA"; Content-Type: text/plain;
/Users/exampleUser/Documents/file1.xml
--boundary

In XML this is represented by setting the type attribute on the I/O element to file. The path child element is then used to set the file path on the server.

XML

<inputA type="file">
  <path>/Users/exampleUser/Documents/file1.xml</path>
</inputA>

In JSON this is represented by setting the type key to file. The path key is then used to set the file path on the server.

JSON

{
 "inputA": {
   "type": "file",
   "path": "/Users/exampleUser/Documents/file1.xml"
 }
}

File Objects

Files can be uploaded via multipart/form-data.

For XMLInput set the Content-Type to application/xml, text/xml or text/html

For DITAMapInput set the Content-Type to application/zip

For DocxInput set the Content-Type to application/vnd.openxmlformats-officedocument.wordprocessingml.document

CODE

Content-Disposition: form-data; name="inputA"; filename="inputA.docx"
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
(data)

XML Strings

XML can be used directly from multipart/form-data. To specify this use application/xml, text/xml or text/html as the Content-Type of the part, for example:

CODE

Content-Type: multipart/form-data; boundary=boundary-id
Content-Length: number_of_bytes_in_entire_request_body
--boundary-id
Content-Disposition: form-data; name="inputA"; Content-Type: application/xml;
<root><a/></root>
--boundary-id
Content-Disposition: form-data; name="inputB"; Content-Type: application/xml;
<root/>
--boundary-id

Cloud

It is possible to use the REST service with Amazon Web Services (AWS) S3, Microsoft Azure Blob storage and Google Cloud Storage. Other providers may be added in a later release. Contact DeltaXML about your I/O requirements to request access using a different service.

In order to make use of this functionality, you must provide the necessary information for each service and POST a comparison request. For further details on how to generate the necessary information, please refer to the documentation for your chosen provider.

If you do not wish to upload the resultant file to your chosen services bucket then do not specify the output element, only the input elements. The file can then be downloaded through a GET request on the 'downloads' URI - See How to Start a ConversionQA Job .

Asynchronous comparison is recommended when using Cloud I/O as the REST service needs to make additional HTTP requests to retrieve your data.

AWS S3

XML

XML

<inputA type="aws_s3">
    <accessKeyId>your_aws_key_id</accessKeyId>
    <secretAccessKey>your_aws_secret_access_key</secretAccessKey>
    <region>your_aws_region</region>
    <bucket>your_bucket_name</bucket>
    <fileName>input_a_file_name</fileName>
    <dxFormat>xml</dxFormat>
</inputA>

JSON

JSON

{
  "inputA": {
    "type": "aws_s3",
    "accessKeyId": "your_aws_key_id",
    "secretAccessKey": "your_aws_secret_access_key",
    "region": "your_aws_region",
    "bucket": "your_bucket_name",
    "fileName": "input_a_file_name",
    "dxFormat": "xml"
  }
}

Azure Blob

This connector has been coded to use the Account Key method of authentication. For more information, see Azure's documentation.

XML

XML

<inputA type="azure_blob">
    <accountName>your_azure_storage_account_name</accountName>
    <accountKey>your_azure_storage_account_key</accountKey>
    <container>your_container</container>
    <blobName>your_input_a_blob_name</blobName>
    <dxFormat>xml</dxFormat>
</inputA>

JSON

JSON

{
  "inputA": {
    "type": "azure_blob",
    "accountName": "your_azure_storage_account_name",
    "accountKey": "your_azure_storage_account_key",
    "container": "your_container",
    "blobName": "your_input_a_blob_name",
    "dxFormat": "xml"
  }
}

Google Cloud Storage

This connector has been coded to use the Service Account Key method of authentication. For more information, see https://cloud.google.com/docs/authentication/getting-started.

We recommend setting the GOOGLE_APPLICATION_CREDENTIALS environment variable pointing to your Google Cloud credentials file so you don’t need to point to it in every request. See Google’s documentation for more information: https://cloud.google.com/docs/authentication/application-default-credentials#GAC

XML

Using default authentication : Set by environment variable

XML

    <inputA type="google_cloud">
        <bucket>your_bucket_name</bucket>
        <fileName>input_a_path</fileName>
        <dxFormat>xml</dxFormat>
    </inputA>

OR

By specifying credentials file

JSON

    <inputA type="google_cloud">
    	<credentialsFile type="file">
    		<path>your_credentials_file_path</path>
    	</credentialsFile>
        <bucket>your_bucket_name</bucket>
        <fileName>input_a_path</fileName>
        <dxFormat>xml</dxFormat>
    </inputA>

JSON

Using default authentication : Set by environment variable

XML

{
    "inputA": {
    	"type": "google_cloud",
        "bucket": "your_bucket_name",
        "fileName": "input_a_path",
        "dxFormat": "xml"
    }
}

OR

By specifying credentials file

JSON

{
    "inputA": {
    	"type": "google_cloud",
        "credentialsFile": {
	    	"type": "file",
	        "path": "your_credentials_file_path"
    		},
        "bucket": "your_bucket_name",
        "fileName": "input_a_path",
        "dxFormat": "xml"
    }
}