1. Implementation Guide
  2. Implementation Tools
  3. File Transfer Services
  4. FTS API Specification

FTS API Specification

An example shell script implementing these API calls can be found in Sample Public File Transfer Script for Planning Apps and Sample Public File Transfer Script for RI and AIF. The sample script will require all of the parameters discussed so far in this chapter to be added to it before it can be used to issue FTS commands. Refer to the table below for a more detailed list of services available in FTS.

Note:

The baseUrl in these examples is not the same as the BASE_URL variable passed into cURL commands. The baseUrl for the API itself is the hostname and tenant, plus the service implementation path (for example, RetailAppsPlatformServices). The sample scripts provided in the appendix show the full path used by the API calls.

Ping

Returns the status of the service, and provides an external health-check.

Method

GET

Endpoint

{baseUrl}/services/private/FTSWrapper/ping

Parameters

Common headers

Request

None

Response

{ appStatus:200 }

The appStatus code follows HTTP return code standards.

List Prefixes

Returns a list of the known storage prefixes. These are analogous to directories, and are restricted to predefined choices per service.

Method

GET

Endpoint

{baseUrl}/services/private/FTSWrapper/listprefixes

Parameters

Common headers

Request

None

Response

A JSON array of strings containing the known prefixes.

List Files

Returns a list of the file within a given storage prefix.

Method

GET

Endpoint

{baseUrl}/services/private/FTSWrapper/listfiles

Parameters

Common headers

Request

Query parameters (…/listfiles?{parameterName}) that can be appended to the URL to filter the request:

prefix – the storage prefix to use

contains – files that contain the specified substring

scanStatus – file status returned by malware/antivirus scan

limit – control the number of results in a page

offset – page number

sort – the sort order key

Response

A JSON resultSet containing array of files. For each file, there is metadata including: name, size, created and modified dates, scan status and date, scan output message.

Move Files

Moves one or more files between storage prefixes, while additionally allowing the name to be modified

Method

GET

Endpoint

{baseUrl}/services/private/FTSWrapper/movefiles

Parameters

Common headers

Request

An array of files containing the current and new storage prefixes and file names, as shown below.

{"listOfFiles": [
	{"currentPath": 
		{ "storagePrefix": "string",
			"fileName": "string"}, 
			"newPath": {
				"storagePrefix": "string", 
				"fileName": "string"
			}
		}
	]
}

Response

HTTP 200, request succeeded;

HTTP 500, an error was encountered.

Delete Files

Deletes one more or files

Method

DELETE

Endpoint

{baseUrl}/services/private/FTSWrapper/delete

Parameters

Common headers

Request

A JSON array of files to be deleted. One or more pairs of storagePrefix and filename elements can be specified within the array. 

{"listOfFiles": 
	[ 
		{
			"storagePrefix": "string",
			 "fileName": "string"
		}
	]
}

Response

A JSON array of each file deletion attempted and the result.

Request Upload PAR

Request PAR for uploading one or more files

Method

POST

Endpoint

{baseUrl}/services/private/FTSWrapper/upload

Parameters

Common headers

Request

A JSON array of files to be uploaded. One or more pairs of storagePrefix and filename elements can be specified within the array. 

{ "listOfFiles":
	 [ 
		{
			"storagePrefix": "string",
			"fileName": "string"
		}
	]
}

Response

A parList containing an array containing elements corresponding to the request including the PAR accessUri and name of file.

Request Download PAR

Request PARs for downloading one or more files

Method

POST

Endpoint

{baseUrl}/services/private/FTSWrapper/download

Parameters

Common headers

Request

A JSON array of files to be downloaded. One or more pairs of storagePrefix and filenames can be specified within the array.

{ "listOfFiles":
	[
		{
			"storagePrefix": "string", 
			"fileName": "string"
		}
	]
}

Response

A parList containing an array containing elements corresponding to the request including the PAR accessUri and name of file.