REST file transfer API reference

The iLink REST file transfer API is RESTful. The API authorisation framework is Client authenticated TLS.

The intended audience of this document is:

• Server administrators who wish to use the provided command line scripts, and
• Software developers who wish to implement this file transfer API in their software.

Download sample code.

Quick start

1. Qvalent implementation consultant creates an iLink test account for the customer's technical contact.
2. Customer contact completes iLink connectivity wizard.
3. Customer develops REST connectivity solution.
4. Qvalent implementation consultant configures file routing.
5. Customer undertakes testing in the test environment.
6. Once customer is satisfied that testing is complete a sign off email is required to progress into production.
7. Qvalent implementation consultant creates an iLink production account for the customer's technical contact.
8. Customer contact completes iLink connecivity form in production iLink.
9. Qvalent implementation consultant configures file routing.
10. Customer tests the REST connection in the live environment.
11. Once this testing is successful customers can perform low value live testing of the other Westpac products that are being implemented.

Integration options

The REST File Transfer API is provided to allow your system to easily upload files to iLink and download files from iLink. You have two integration options:

1. Use the provided command-line scripts. These scripts use the cURL command line program and standard in and out streams to transfer files. Minimal configuration work is required.
2. Write code to generate HTTPS requests sent to iLink and interpret the responses you receive. A moderate amount of development work is required, and you will need previous expertise with HTTPS.

iLink URLs

iLink connectivity setup

In the early stages of your Westpac project you will be asked to provide the contact details of the IT person who will be responsible for setting up your connection.

Once these details are received you will be provided with an iLink login to enter your IP addresses.

The iLink connectivity process has the following steps:

1. The Qvalent implementation consultant will provide the user's technical contact with a login to the iLink test instance.
2. Fill in the setup connectivity form and submit.
3. Notify your Qvalent and Westpac implementation managers that you have completed the connectivity form.
4. The Qvalent implementation consultant will configure the file routing and notify all stakeholders when this is done.
5. User to send and receive test files to confirm the connection.
6. Once the Qvalent implementation consultant has received confirmation that all relevant testing has been completed steps 1 - 5 will need to be repeated in the production environment.

Setup connectivity form

To setup your connectivity, click the Connectivity menu option at the top of the screen, then click the Setup connectivity button.

The Setup connectivity page will be displayed where you can enter the following details:

• Contact emails - Add any additional email addresses that should receive connectivity related emails.
• PGP key - Upload your PGP key here.
• IP addresses - The iLink solution has a white list of IP addresses accepted for each user. Users need to provide the IP address or addresses that their incoming requests will be coming from, this is the external IP address taking into account any proxy servers or other externally facing network infrastructure. This can be found by logging on to iLink on your server and taking the browser address shown in the IP addresses section of the connectivity form.

After you click Save, you will be able to access the Connectivity details page containing the following information:

• Westpac's keys - This is the public key that you will need to use to decrypt the files you receive from iLink. This will only be displayed if encryption is enabled.
• Your keys - You can use these fields during testing to confirm which keys you have loaded into iLink. This will only be displayed if encryption is enabled.
• Your credentials - This section contains the details of the client certificate that you will use to authenticate with the iLink server.
• IP addresses - Lists the IP addresses allowed to access this connectivity.

Using the command line scripts

Command line scripts have been provided for Unix and Windows that demonstrate the use of cURL to upload and download files.

The scripts have been designed to exit with an error code if the file could not be successfully uploaded or download. Error details will be written to the standard error stream.

Downloading cURL

You will need to download the cURL client for your platform from http://curl.haxx.se/download.html. Be sure to download the correct distribution for your server's operating system. You must download a version that includes TLS support.

Configuration

You need to edit the configuration script before you can use the upload or download scripts. The configuration script is named config.cmd on Windows and config.sh on Unix.

Open the file in a text editor and make the following changes:

1. Set the CERT_FILE variable to the file path of your .pem certificate file, e.g. c:\fileTransfer\certificate.pem.
2. Set the CERT_PASSWORD variable to the password for your .pem certificate file.
3. If you require a proxy to connect to the internet: a. Uncomment the first PROXY_OPTIONS line and change proxy_address to the host name of your proxy server, and proxy_port to the port number your proxy server listens on. b. If your proxy server requires authentication, uncomment the second PROXY_OPTIONS line and change username to your proxy username and password to your proxy password.
4. If you are uploading and downloading files in the test environment, leave the BASE_URL variable set to https://ws.support.qvalent.com/. If you are uploading and downloading files in the production environment, set the BASE_URL variable to https://ws.qvalent.com/.
5. Set the CURL_EXE variable to the file path of the cURL executable file, e.g. c:\curl-7.21.0\curl.exe.

Uploading files

The upload script is named uploadFile.cmd on Windows and uploadFile.sh on Unix. It takes one argument, which is the file name to send to iLink. The file contents are read from standard in.

The following example shows how to send a file from the file system. Note that this allows the file name sent to iLink to be different from the file name on disk.

Windows

uploadFile.cmd mts20100830_01.txt < c:\mts20100830.txt

Unix

uploadFile.sh mts20100830_01.txt < c:\mts20100830.txt

File names

The file name sent to iLink must be unique. If you send a different file with the same name as a previous file, you will receive a HTTP 400 Bad Request error response. To ensure uniqueness of file names, include the file type, date and a daily sequence number in the file name.

Handling errors

If you receive a network error while transmitting your file, you can simply run the same upload command again (re-using the same file name). This will never result in a duplicate file because iLink will silently ignore duplicate files with the same name.

If you receive any other error, it is likely a configuration issue you need to investigate based on the error message provided.

Downloading files

The download files script is named downloadFiles.cmd on Windows and downloadFiles.sh on Unix. It downloads all your available files and removes them from the download list (preventing duplicate downloads).

By default, the file contents are echoed to standard out. You will need to modify this script to save the files to an appropriate location and trigger any required file processing.

Windows

downloadFiles.cmd

Unix

downloadFiles.sh

Handling errors

To download the available files, the script performs the following operations:

1. Get a list of all the available files.
2. For each file in that list:
   1. Download the file.
   2. If the file has not already been processed, run your custom file processing.
   3. Delete the file (removing it from the available file list).

Operations 1, 2.1 and 2.3 can fail due to network errors. In that event, simply run the download script again and the file will be downloaded again. The file is not deleted until it is downloaded and processed, which allows you to retry the download operation in the event of a failure.

If you receive an error not related to network connectivity or your processing, it is likely a configuration issue you need to investigate based on the error message provided.

Developing custom REST connectivity

This section gives an overview of developing your own connectivity code to use the HTTPS file transfer service. It details the requirements of your system and gives instruction on how to integrate the file transfer protocol into your system. This section does not contain details of the file transfer protocol itself. That information is in iLink REST API Reference.

Note that this section only gives a general overview of what needs to be done. Specific details are not provided since they vary depending on the actual technology you use. For this reason, Westpac can provide only limited assistance to customers using custom integration. We recommend that you only undertake a custom integration if you have previous experience with HTTPS and client certificates.

To use the iLink HTTPS file transfer service, you will need a HTTP client that supports the following standards:

• HTTP 1.1 - http://www.ietf.org/rfc/rfc2616.txt
• TLS 1.2 or higher - http://www.ietf.org/rfc/rfc2246.txt

Recommendations

• Log detailed information about each file you upload and download. This information will help you diagnose any potential problems you may encounter later. You should not log your certificate details or any full credit card numbers contained in the file.
• Protect your certificate file. If necessary, restrict the permissions on this file so that only your application can access the certificate.

Handling errors

If you encounter a network error or HTTP 500 response code, your system should automatically retry the request. You should wait at least 5 minutes before retrying the request, and you should only retry for a maximum of 4 hours before you investigate the cause of the issue manually.

Installing the client certificate

You must use an TLS client certificate to communicate with the iLink server. You will download this certificate from the iLink web interface. You may not use a certificate from another source (e.g. Verisign).

• Your certificate is generally provided in PKCS12 (or PFX) format. This file format requires a password for the certificate. You will be provided with this certificate password. Do not confuse this password with the password you use to login to any Westpac websites. Your certificate password will always start with a C.
• A few HTTP libraries require the client certificate file to be in PEM format. If this is the case, please ensure that you get the certificate in the correct format.
• Once you have obtained your certificate in the correct format, you must reference it from your HTTP library. The details of this will vary between HTTP libraries, so consult the documentation for your HTTP library.
• Be sure to document the procedure to install the certificate, since the certificate must be replaced every two years.

Protecting your certificate

Your certificate file is used to authorise your requests to the iLink server. Do not give your certificate file to anyone. Never email your certificate in clear text. Always use a secure method to copy your certificate file to your server.

Upgrading your certificate

Your certificate is valid for a maximum of two years. When your certificate is near expiry, you will be contacted by Westpac with details on how to get a new certificate file. The steps to install your new certificate will vary depending on your technology, so it is important to document this procedure for later use.

REST API reference

This section documents the iLink REST File Transfer API for uploading and downloading files.

Authentication is based on your client certificate and the IP address that your request comes from.

Upload file

Upload a file to iLink. Include the file name in the URL, the additional headers and the file contents in the HTTP request body.

Request

POST /uploadedFiles/{fileName}

Path parameters

Additional headers

Provide the following headers:

Request parameters

None.

Request body

The content of the file you are uploading.

Example

POST /services/messaging/rest/uploadedFiles/de20100831_01.txt HTTP/1.1
Content-Type: application/octet-stream
Host: ws.qvalent.com:443
Content-Length: 19

This is a test file

Response

If successful, this method returns a HTTP 202 Accepted.

HTTP status codes

Error handling

If you receive a network error or HTTP 500 status when transmitting your file, you can simply run the same upload command again (re-using the same file name). This will never result in a duplicate file because iLink will silently ignore duplicate files with the same name.

If you receive any other error, it is likely a configuration issue you need to investigate based on the error message provided.

Example

HTTP/1.1 202 Accepted
Content-Length: 0
Date: Mon, 30 Aug 2010 23:24:20 GMT

List files

Use this resource to list files for download. You can choose the format of the file list using the HTTP Accept header.

Request

To get the list of files for download, send a GET to the following URL.

GET /filesForDownload

Path parameters

None.

Additional headers

Provide the following headers:

Request parameters

None.

Request body

None.

Example HTTP request where the file list is requested in plain text format:

GET /services/messaging/rest/filesForDownload/ HTTP/1.1
Accept: text/plain
Host: ws.qvalent.com:443

Example HTTP request where the file list is requested in XML format:

GET /services/messaging/rest/filesForDownload/ HTTP/1.1
Accept: application/xml
Host: ws.qvalent.com:443

Response

If successful, this method returns a HTTP 200 OK and a list of files in plain text or XML.

The returned list is ordered alphabetically and has a maximum length of 1000 files. You should delete files after they have been downloaded and processed by your system. This ensures the list will only contain files that are yet to be processed by your system.

HTTP status codes

Error handling

Requesting the list of files for download does not change the server state in any way, so you can safely request the list as many times as you need to. If you receive a network error or HTTP 500 status when requesting the list, you can simply repeat the same request again.

Example HTTP response in plain text

HTTP/1.1 200 OK
Expires: 0
Pragma: no-cache
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Content-Type: text/plain
Date: Mon, 30 Aug 2010 23:24:20 GMT
Transfer-Encoding: chunked

16
File1.txt
File2.txt

0

Example HTTP response in XML

HTTP/1.1 200 OK
Expires: 0
Pragma: no-cache
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Content-Type: text/xml
Date: Mon, 30 Aug 2010 23:24:20 GMT
Transfer-Encoding: chunked

e8
<?xml version="1.0" encoding="UTF-8"?>
<downloadFileList
xmlns="http://www.qvalent.com/soap/namespace/messaging/DownloadFiles">
<file>
<fileName>File1.txt</fileName>
<fileName>File2.txt</fileName>
</file>
</downloadFileList>

0

Download file

Use this resource to download the content of a file.

Request

To download a file, select the file name from the list of files available for download and send a GET to the following URL.

GET /filesForDownload/{fileName}

Path parameters

Request parameters

None.

Request body

None.

Example

GET /services/messaging/rest/filesForDownload/File1.txt HTTP/1.1
Host: ws.qvalent.com:443

Response

If successful, this method returns a HTTP 200 OK and the file contents are returned in the response body.

HTTP status codes

Error handling

Downloading a file does not change the server state in any way, so you can safely download the same file multiple times. If you receive a network error or HTTP 500 status when downloading the file, you can simply repeat the same download request again.

If you receive any other error, it is likely a configuration issue you need to investigate based on the error message provided.

Example

HTTP/1.1 200 OK
Expires: 0
Pragma: no-cache
Cache-Control: no-store, no-cache, must-revalidate, proxy-revalidate
Content-Type: application/octet-stream
Date: Mon, 30 Aug 2010 23:24:20 GMT
Transfer-Encoding: chunked

13
This is a test file
0

Delete file

Use this resource to delete a file from a list of the available files for download.

Request

Send a HTTPS DELETE to the following URL.

DELETE /filesForDownload/{fileName}

Path parameters

Request parameters

None.

Request body

None.

Example

DELETE /services/messaging/rest/filesForDownload/File1.txt HTTP/1.1
Host: ws.qvalent.com:443

Response

If successful, this method returns a HTTP 204 NO CONTENT and the file will be deleted from the list.

HTTP status codes

Error handling

If you receive a network error or HTTP 500 status, you can simply repeat the same delete request again. If the file has already been deleted, the server will ignore the delete request and return a HTTP 204 status. If you receive any other error, it is likely a configuration issue you need to investigate based on the error message provided.

Example

HTTP/1.1 204 No Content
Date: Mon, 30 Aug 2010 23:24:20 GMT
Transfer-Encoding: chunked

0

Troubleshooting

Curl: (22) The requested URL returned error: 502

This may occur when executing downloadFile.cmd. This error means the file you are trying to fetch may have a space in its name. Contact Westpac and ask them to check that there is no space in the filenames being fetched.