Managing Files

This describes the web services that manage media, message media and REST log files that reside on the file store for an account on Aculab Cloud.

When specifying directories, use forward slash as the delimiter.

For services that accept a filetype parameter, the options are "media", "msg_media" or "rest". These correspond to Media, Message media and REST log on the Files menu of the Cloud Console. When working with REST application log files, choose "rest". When working with wav or tiff files, for UAS or REST applications, choose "media". When working with image files for messages, choose "msg_media".

Any image file formats can be uploaded for message media and for these files, it is recommended that you set contenttype.

Media files (unencrypted)

Unencrypted media files are uploaded using File Write. Their format is immediately checked for compatibility. Files that are uploaded for the first time (unique name) will then be immediately available in the media store. Files that are uploaded that overwrite existing files may take some time to be updated across the system.

Media files (encrypted)

To upload a file that you have encrypted, use File Write with the encrypted flag set to true.

Note that encrypted files cannot be checked for compatibility on upload, as they are encrypted. Instead they will be validated just before use when your application provides the decryption keys. For REST, this will be done automatically when you request an action that uses the encrypted file. For UAS, you request the validation and file use seperately in your application. This allows your application to check that it has a valid file before taking further actions.

Messsage media does not support encrypted files.

Note

This is a low level API. For information on higher level APIs see the Web Services Language Wrappers

Authorisation

This API uses basic authentication, using your cloud account username and API Access Key.


Username	: cloudID/username (e.g. 1-2-0/bob@example.com)
Password	: API Access Key

File List

This lists all the files of a specified type present on the file store of a cloud account. An optional prefix can be specified to determine a subset of files to list.

Request


Url	: https://ws-[cloudID].aculabcloud.net/file_list
Methods	: GET, POST

Parameter	Required/Optional	Default	Description
filetype	required		The type of files to list ("media", "msg_media" or "rest").
filename	optional	(all files)	A filename to match. Matches one file with this string. An empty string matches all files in all folders. The last character can be a '*' wildcard in which case the preceding filename acts exactly as prefix does and lists all files that start with it. If both filename and prefix are provided, filename takes precedence.
prefix	optional		A prefix to match. Matches any file whose name starts with the string. If both filename and prefix are provided, filename takes precedence.
maxcount	optional	10000	The maximum number of files to list. The default is also the maximum value for this parameter.
to	optional		Indicates a selected range of files to list, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit return of filenames where the modified date is up to the time (inclusive) given. May be used with from to select ranges of dates.
from	optional)		Indicates a selected range of files to list, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit return of filenames where the modified date is after the time (inclusive) given. May be used with to to select ranges of dates.
startafter	optional		A filename to use to start listing files after. Use the last filename from a previous result to page through all available media files.
startpos (deprecated)	optional		Deprecated. Use startafter instead.

Response

A JSON object containing the files stored on the cloud account together with details of each file represented in a JSON object.

Parameter	Type	Availability	Description
modified	string	always	The last modification time for the file formatted as YYYY-MM-DD_hh:mm:ss.
size	integer	always	The size of the file in bytes.
encrypted	boolean	always	true if the file is encrypted, false if the file is unencrypted.
expiry_date	string	always	The expiry date (UTC) of the file formatted as YYYY-MM-DD_hh:mm:ss. It is empty if time to live has not been set.

Example

Request

https://ws-[cloudID].aculabcloud.net/file_list?filetype=media&prefix=recordings/voice

Response

  {
    "recordings/voicemail/recording_1.wav":
    {
      "modified": "2016-09-30_05:54:47", 
      "encrypted": true,
      "size": 254034,
      "expiry_date": "2017-01-20_10:34:00" 
    }, 
    "recordings/voicemail/recording_2.wav":
    {
      "modified": "2016-09-30_10:31:44", 
      "encrypted": false,
      "size": 245634
    } 
  }

Folder List

This shows a folder view of a given folder name on the file store of an account, listing all the files and folders within that folder.

Request


URL	: https://ws-[cloudID].aculabcloud.net/folder_list
Methods	: GET, POST

Parameter	Required/Optional	Default	Description
filetype	required		The type of files to list ("media", "msg_media" or "rest").
foldername	optional	(the root folder)	A folder name to list. Matches the folder whose name equals the string. A trailing '/' is allowed, but not required. An empty string matches the root folder.
prefix	optional	(all files)	A prefix to match. Matches any file whose name within the folder starts with the string. An empty string matches all files.
maxcount	optional	10000	The maximum number of files to list. The default is also the maximum value for this parameter.
startafter	optional		A filename to use to start listing files after. Use the last filename from a previous result to page through all available media files.
to	optional		Indicates a selected range of folders and files to list, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit return of folders and filenames where the modified date is up to the time (inclusive) given. May be used with from to select ranges of dates.
from	optional		Indicates a selected range of folders and files to list, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit return of folders and filenames where the modified date is after the time (inclusive) given. May be used with to to select ranges of dates.

Reponse

A JSON object containing the following parameters:

Parameter	Type	Availability	Description
folders	array	always	An array of folder objects each representing a folder within the specified folder path.
files	array	always	An array of file objects each representing a file within the specified folder path.
startafter	string	present if additional files are available from a further folder_list call	The name of a file within the specified folder path that can be used to obtain the next available folders and files.

Folder object

Parameter	Type	Availability	Description
name	string	always	The name of the folder including the trailing "."

File object

Parameter	Type	Availability	Description
name	string	always	The name of the file.
size	integer	always	The size of the file in bytes.
modified	string	always	The last modification time for the file formatted as YYYY-MM-DD_hh:mm:ss.
encrypted	bool	always	true if the file is encrypted, false if the file is unencrypted.
expiry_date	string	always	The expiry date (UTC) of the file formatted as YYYY-MM-DD_hh:mm:ss. It is empty if time to live has not been set.

Example

Request

https://ws-[cloudID].aculabcloud.net/folder_list?filetype=media&foldername=test&prefix=record

Response

{
    "folders": [
        {
            "name": "test/recording_archive/"
        }
    ],
    "files": [
          {
            "name": "test/recording1.wav",
            "modified": "2022-02-01_12:01:32",
            "encrypted": false,
            "expiry_date": "",
            "size": 188490
        }
    ]
}

File Write

This uploads a local media or msg_media file onto the cloud file store for a cloud account.

Only .wav audio and .tif image media files can be uploaded when filetype paramater is set to media. The .tif files are constrained to fax format images.

For msg_media filetypes any file type is allowed, though .gif, .jpg and .png files are checked for correct formatting.

See the Media File Names and Extensions guide regarding file name character and extension restrictions when uploading to the cloud file store.

For a PUT, the file data to upload is the body of the request. For a POST, the body must contain an HTML form, the file data being the value of one of its fields.

Files that are uploaded for the first time (unique name) will then be immediately available in the media store. Files that are uploaded that overwrite existing files may take some time to be updated across the system.

Unencrypted media files

Unencrypted media file formats are checked for compatibility during upload.

Encrypted media files

To upload a file that you have encrypted, set the encrypted flag to true.

The format of an encrypted file cannot be checked for compatibility on upload, as it is encrypted. Instead it will be validated just before use when your application provides the decryption keys. For REST, this will be done automatically when you request an action that uses the encrypted file. For UAS, you request the validation and file use seperately in your application. This allows your application to check that it has a valid file before taking further actions.

Request


URL	: https://ws-[cloudID].aculabcloud.net/file_write
Methods	: POST, PUT

Parameter	Required/Optional	Default	Description
filetype	required		The type of files to write ("media" or "msg_media").
filename	required		The target filename on the cloud file store, including path.
encrypted	optional	false	Whether the file is encrypted ("true", "false").
time_to_live	optional	unlimited	The time to live (TTL) of the file, expressed as Xm (X minutes), Xh (X hours), or Xd (X days).
contenttype	optional	derived from file extension	The media type (also called the MIME type) is derived from the filename extension by default. If the mediatype cannot be guessed, or the default needs to be overridden, then it can be set here. (For example, "image/jpeg".)

Example

Request

https://ws-[cloudID].aculabcloud.net/file_write?filetype=media&filename=mediafiles/message_1.wav

File Move

This renames a file that is present on the file store of a cloud account.

See the Media File Names and Extensions guide regarding file name character and extension restrictions when moving existing files on the cloud file store.

Request


URL	: https://ws-[cloudID].aculabcloud.net/file_move
Methods	: GET, POST, HEAD

Parameter	Required/Optional	Description
filetype	required	The type of file to rename ("media" or "msg_media").
from	required	The filename of the file to rename, including path.
to	required	The target filename, including path.

Response

Nothing.

Example

Request

https://ws-[cloudID].aculabcloud.net/file_move?filetype=media&from=rec_1.wav&to=rec_2.wav

File Get

This downloads a file present on the file store of a cloud account.

Request


URL	: https://ws-[cloudID].aculabcloud.net/file_get
Methods	: GET, POST, HEAD

Parameter	Required/Optional	Default	Description
filetype	required		The type of file to get ("media", "msg_media" or "rest").
filename	required		The filename of a file on the file store on the cloud to download. This must be an exact match of the file that is to be downloaded. Only one file can be downloaded at a time.

Response

The file data.

Example

Request

https://ws-[cloudID].aculabcloud.net/file_get?filetype=rest&filename=/2013/11/07/rest_16_39_23_058d242936dcc5f9.47610.log

File Delete

This deletes one or more files from the file store of a cloud account. Call File Delete Progress to monitor the progress of the deletion of multiple files.

Request


URL	: https://ws-[cloudID].aculabcloud.net/file_delete
Methods	: DELETE, GET, POST

Parameter	Required/Optional	Default	Description
filetype	required		The type of file to delete ("media", "msg_media" or "rest").
filename	required		A filename specifying the file to delete. This can be a prefix followed by a '' to match all files and directories starting with the prefix. Setting to '' will delete all files.
to	optional	all that match	Indicates a selected range of files to delete, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit deletion of files where the modified date is up to the time (inclusive) given. May be used with from to select ranges of dates.
from	optional	all that match	Indicates a selected range of files to delete, in the format YYYY-MM-DD_hh:mm:ss. If specified, will limit deletion of files where the modified date is after the time (inclusive) given. May be used with to to select ranges of dates.

Response

A JSON object that contains the following properties:

Parameter	Type	Availability	Description
token	string	Always	A token that identifies the deletion requested. This token can be used with the file_delete_progress web service to monitor the progress of a deletion.

Example

Request

https://ws-[cloudID].aculabcloud.net/file_delete?filetype=media&filename=voicemail*

Response

  {
    token: "2e8903c1_2.1367569618.101"
  }

File Delete Progress

This retrieves the progress of a file deletion from a cloud account initiated by File Delete.

Request


URL	: https://ws-[cloudID].aculabcloud.net/file_delete_progress
Methods	: GET, POST

Parameter	Required/Optional	Default	Description
token	required		A token returned by a call to the file_delete web service.

Response

A JSON object describing the status of the deletion.

Parameter	Type	Availability	Description
status	string	always	The status of the deletion. Either "in progress" or "completed".
files_deleted	integer	always	The number of files deleted. This value will be updated in chunks of up to 10k files while status is 'in progress'. Once the status is 'deleted' then it will contain the total number of files deleted.

Example

Request

https://ws-[cloudID].aculabcloud.net/file_delete_progress?token=2e8903c1_2.1367569618.101

Response (200)

  {
    "status": "in progress",
    "files_deleted": 10000
  }

Response (400)

{
    "error": {
        "code": "0001",
        "text": "'token' is not specified.",
        "datetime": "2022-12-12_11:28:49",
        "link": "https://docs.cloud.aculab.com/Web_Services_API/web_service_errors/#error-0900"
    },
    "request": {
        "datetime": "2022-12-12_11:28:49",
        "url": "/file_delete_progress"
    }
}

Response (404)

{
    "error": {
        "code": "0405",
        "text": "Invalid token; token is either invalid, lapsed, or otherwise unidentified.",
        "datetime": "2022-12-12_11:32:41",
        "link": "https://docs.cloud.aculab.com/Web_Services_API/web_service_errors/#error-0405"
    },
    "request": {
        "datetime": "2022-12-12_11:32:41",
        "url": "/file_delete_progress"
    }
}