Upload
urooj230
View
48
Download
2
Embed Size (px)
DESCRIPTION
Citation preview
Thru REST API 1.0 / Reference 1.7 www.thruinc.com | © 2014 Thru, Inc. All rights reserved
Thru REST API Version 1.0 Programming Reference Version 1.7
PROGRAMMING REFERENCE
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 2
Table of Contents
Table of Contents .......................................................................................................................................................... 2
1 General .................................................................................................................................................................. 5
2 Overview ................................................................................................................................................................ 6
2.1 Web Service REST Design ............................................................................................................................ 6
2.2 Versioning ...................................................................................................................................................... 7
3 Thru REST Services API Security ....................................................................................................................... 8
3.1 Access Signature (HTTP Header) ................................................................................................................. 8
4 Exception Handling .............................................................................................................................................. 9
4.1 Error Response .............................................................................................................................................. 9 4.1.1 Error Data Transfer Object ........................................................................................................................ 9
4.2 Error Codes .................................................................................................................................................... 9
5 Web Service Data Specifications ...................................................................................................................... 10
5.1 API Data Types ............................................................................................................................................ 10
5.2 API Complex Data Constructions ................................................................................................................ 10
5.3 Session Resources ...................................................................................................................................... 10 5.3.1 ThruSessionRequest Structure ............................................................................................................... 10 5.3.2 ThruPublicSession Structure ................................................................................................................... 11
5.4 File System Resources ................................................................................................................................ 12 5.4.1 ThruPublicFolderInfo Structure ................................................................................................................ 12 5.4.2 ThruPublicFileInfo Structure .................................................................................................................... 14 5.4.3 ThruPublicContentResult Structure ......................................................................................................... 16
5.5 Message Resources .................................................................................................................................... 17 5.5.1 ThruPublicMessageInfo Structure ........................................................................................................... 17 5.5.2 ThruPublicMessagesListResult Structure ............................................................................................... 20 5.5.3 ThruPublicMessageRecipientInfo ............................................................................................................ 21
5.6 Search Resources ....................................................................................................................................... 22 5.6.1 ThruPublicSearchCriteria Structure ......................................................................................................... 22
5.7 Server Resources ........................................................................................................................................ 24 5.7.1 ThruPublicServerInfo Structure ............................................................................................................... 24 5.7.2 ThruMessageSettings Structure .............................................................................................................. 24 5.7.3 ThruPasswordSettings Structure ............................................................................................................. 26 5.7.4 ThruUploadSettings Structure ................................................................................................................. 27 5.7.5 ThruMobileSettings .................................................................................................................................. 29
5.8 System Log Resources ................................................................................................................................ 29 5.8.1 ThruPublicSystemLogOperation.............................................................................................................. 29
5.9 Ticket Resource ........................................................................................................................................... 30 5.9.1 ThruTicketInfo Structure .......................................................................................................................... 30
5.10 User Resources ........................................................................................................................................... 31 5.10.1 ThruPublicUserInfo Structure .............................................................................................................. 31 5.10.2 ThruPasswordInfo Structure ............................................................................................................... 33
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 3
5.11 Service Resources ....................................................................................................................................... 33 5.11.1 ThruServiceVersion Structure ............................................................................................................. 33 5.11.2 ThruServiceVersionsResult Structure ................................................................................................. 34
5.12 Server Version Resources ........................................................................................................................... 35 5.12.1 ThruServerVersion Structure .............................................................................................................. 35
6 Web Services ...................................................................................................................................................... 37
6.1 Authentication Service ................................................................................................................................. 37 6.1.1 POST New Session Object ..................................................................................................................... 37 6.1.2 DELETE Existing Session Object ............................................................................................................ 37 6.1.3 CHECK Existing Session Object ............................................................................................................. 37
6.2 File System Service ..................................................................................................................................... 38 6.2.1 POST New Folder Information ................................................................................................................ 38 6.2.2 GET Existing Folder Information ............................................................................................................. 38 6.2.3 PUT Updated Folder Information ............................................................................................................. 39 6.2.4 DELETE Existing Folder .......................................................................................................................... 39 6.2.5 GET Home Folder Information ................................................................................................................ 40 6.2.6 GET List of Files and Folders Inside a Home Folder .............................................................................. 40 6.2.7 GET List of Files Inside a Home Folder .................................................................................................. 41 6.2.8 GET List of Folders Inside a Home Folder ............................................................................................. 41 6.2.9 GET Root Folder Information .................................................................................................................. 41 6.2.10 GET List of Files and Folders Inside a Root Folder ............................................................................ 42 6.2.11 GET List of Files Inside a Root Folder ................................................................................................ 42 6.2.12 GET List of Folders Inside a Root Folder ............................................................................................ 42 6.2.13 GET List of Files and Folders Inside a Folder ..................................................................................... 43 6.2.14 GET List of Files Inside a Folder ......................................................................................................... 43 6.2.15 GET List of Folders Inside a Folder .................................................................................................... 44 6.2.16 GET Existing File Information ............................................................................................................. 44 6.2.17 PUT Updated File Information ............................................................................................................. 44 6.2.18 DELETE Existing File .......................................................................................................................... 45
6.3 Message Service ......................................................................................................................................... 46 6.3.1 POST New Thru Message ....................................................................................................................... 46 6.3.2 GET Existing Thru Message .................................................................................................................... 47 6.3.3 DELETE Existing Thru Message ............................................................................................................. 47 6.3.4 PUT Updated Thru Message ................................................................................................................... 48 6.3.5 PUT Discard Thru Message .................................................................................................................... 49 6.3.6 PUT Complete Thru Message ................................................................................................................. 49 6.3.7 GET SentThru List ................................................................................................................................... 49 6.3.8 POST Project Message Storage ............................................................................................................. 50
6.4 Search Service ............................................................................................................................................. 50 6.4.1 POST Find All Thru Files and Folders by Search Criteria ....................................................................... 50 6.4.2 POST Find All Thru Folders by Search Criteria ...................................................................................... 51 6.4.3 POST Find All Thru Files by Search Criteria ........................................................................................... 51
6.5 Server Service ............................................................................................................................................. 52 6.5.1 GET Server Information ........................................................................................................................... 52 6.5.2 GET Message Settings ............................................................................................................................ 52 6.5.3 GET Password Settings .......................................................................................................................... 52 6.5.4 GET Upload Settings ............................................................................................................................... 53 6.5.5 GET Mobile settings ................................................................................................................................ 53
6.6 Favorites Service ......................................................................................................................................... 53 6.6.1 PUT Folder to Favorites .......................................................................................................................... 53 6.6.2 DELETE Folder from Favorites ............................................................................................................... 54 6.6.3 PUT File to Favorites ............................................................................................................................... 54 6.6.4 DELETE File from Favorites .................................................................................................................... 54
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 4
6.6.5 GET All Content in Favorites ................................................................................................................... 56 6.6.6 GET Files in Favorites ............................................................................................................................. 56 6.6.7 GET Folders in Favorites ......................................................................................................................... 56
6.7 Service Versions Service ............................................................................................................................. 57 6.7.1 GET Information about Service Versions ................................................................................................ 57
6.8 System Log Service ..................................................................................................................................... 57 6.8.1 POST System Log Operation .................................................................................................................. 57
6.9 Ticket Service............................................................................................................................................... 58 6.9.1 POST New Ticket .................................................................................................................................... 58
6.10 User Service................................................................................................................................................. 58 6.10.1 GET User Information ......................................................................................................................... 58 6.10.2 PUT New Password for the User ........................................................................................................ 58
6.11 Server Version Service ................................................................................................................................ 59 6.11.1 GET Information About Server Version............................................................................................... 59
7 Programmatic File and Folder Transfers. ........................................................................................................ 60
7.1 Downloading. ............................................................................................................................................... 60
7.2 Uploading Files and Folders via basic protocol (deprecated) ...................................................................... 61
7.3 Uploading of files via Extended File Upload/Download Protocol ................................................................. 62
8 File Transfer User Interface Tools .................................................................................................................... 63
8.1 Upload Java/HTML5/HTML4 Tool and API ................................................................................................. 63 8.1.1 Overview .................................................................................................................................................. 63 8.1.2 Security Token ......................................................................................................................................... 63 8.1.3 Upload Tool URL Parameters, option with no Security Token. ............................................................... 64 8.1.4 Upload Tool URL Parameters, option with Security Token. .................................................................... 65 8.1.5 Server Error Codes .................................................................................................................................. 65 8.1.6 JavaScript Samples ................................................................................................................................. 66 8.1.7 URL Samples ........................................................................................................................................... 67
8.2 Java/HTML Download Tool and API ............................................................................................................ 68 8.2.1 Overview .................................................................................................................................................. 68 8.2.2 Security Token ......................................................................................................................................... 68 8.2.3 Download Tool URL Parameters, option with no Security Token ........................................................... 69 8.2.4 Download Tool URL Parameters, option with Security Token ................................................................ 69 8.2.5 Server Error Codes .................................................................................................................................. 71 8.2.6 JavaScript Samples ................................................................................................................................. 71 8.2.7 URL Sample ............................................................................................................................................ 72
Appendix A – Error Codes returned by RESTAPI .................................................................................................... 73
About Trademarks and Abbreviations ...................................................................................................................... 76
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 5
1 General
THE PURPOSE OF THIS DOCUMENT IS TO DESCRIBE THRU WEB SERVICES API, ITS PUBLIC ENDPOINTS, DATA SPECIFICATIONS AND ARCHITECTURE. THE DOCUMENT ALSO REVIEWS THE SECURITY, AUTHENTICATION AND SIDE BY SIDE VERSIONING. WS API IMPLEMENTATION UTILIZES ASP.NET MVC REST SDK WHICH PROVIDES AUTOMATIC SERIALIZATION TO AND FROM THE SERVICE DATA OBJECTS.
THIS REFERENCE GUIDE DESCRIBES AND SUMMARIZES THE THRU REST API. THIS DOCUMENT HAS BEEN PREPARED SOLELY FOR INFORMATIONAL PURPOSES AND IS BEING FURNISHED FOR USE BY CUSTOMERS. DISTRIBUTION OF THIS DOCUMENT IS LIMITED TO CUSTOMERS.
THE REFERENCE GUIDE AND ALL INFORMATION CONTAINED HEREIN ARE OF A CONFIDENTIAL NATURE. EACH RECIPIENT WILL TREAT IT IN A CONFIDENTIAL MANNER. SUCH RECIPIENT WILL, NOT DIRECTLY OR INDIRECTLY, DISCLOSE OR PERMIT ITS AGENTS, REPRESENTATIVES, EMPLOYEES, OFFICERS, DIRECTORS OR AFFILIATES TO DISCLOSE ANY SUCH INFORMATION AND SUCH RECIPIENT WILL USE THE DOCUMENT AND ANY RELATED INFORMATION ONLY TO ACCESS THE THRU SERVICE. IF EITHER THE RECIPIENT OR THE COMPANY ELECTS NOT TO PURSUE OR CONTINUE WITH THE THRU SERVICE, THE RECIPIENT MUST RETURN THIS DOCUMENT AND ANY OTHER MATERIAL RELATING TO THE THRU. SERVICE AND THRU, LLC., WITHOUT RETAINING ANY COPIES THEREOF.
THE INFORMATION CONTAINED HEREIN IS PROVIDED ON A CONFIDENTIAL BASIS AND MAY NOT BE REPRODUCED IN WHOLE OR IN PART.
IF YOU REQUIRE ANY MORE INFORMATION REGARDING THE THRU SERVICE PLEASE CONTACT:
THRU. HELP CENTER [email protected] 800.871. 9316
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 6
2 Overview
2.1 Web Service REST Design
The Thru REST Services API adheres to the following points of the REST paradigm:
• Interaction between client and server is semi-stateless (no connection is established, but session is used to authorize user)
• The API leverages existing features of the HTTP protocol (URL, headers, request body), not requiring any special messaging protocol/library (SOAP or RPC)
• Platform-independence (client can be running on any operating system)
• Language-independence (client can be developed in any language of preference)
• Request body should be present in application/x-www-form-urlencoded format serialized as a standard query string: a=1&b=2&c=3&d=4&e=5 The standard HTTP header Accept is used to define a data format that will be provided for client in Response. The currently supported formats are:
o Accept: application/xml
o Accept: application/json
• Response data are not bound to a specific format (e.g.: SOAP receives and returns data always in XML). Though the standard data exchange format used in REST architectures (as well as in the Thru API) is XML, the Thru API also supports JSON and, in fact, can be expanded to support other formats in the future. The exchanged data format is determined by the standard HTTP headers Content-Type. The currently supported formats:
o Content-Type:application/xml
o Content-Type:application/json
• API endpoints are designed around resources (e.g.: files, messages) that are identified by uniform URIs. For instance, all API endpoints built for dealing with file system objects start with the same URI https://[ThruWebServer]/REST/[version]/FileSystem. The type of action to be performed on the resource is designated by passing standard HTTP verbs:
o GET (Retrieve resource/resources)
o POST (Create a new resource)
o PUT (Update an existing resource)
o DELETE (Delete an existing resource)
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 7
2.2 Versioning
To support changes in the API signature, without breaking existing clients, the Thru REST Services API supports side-by-side versioning. Different versions of the same endpoints can be made available using different URIs, based on the version number.
For instance, if the Thru REST Service API has two versions (1.0 and 1.1), we have two sets of the File URIs:
Version 1.0: http://[ThruWebServer]/REST/1.0/FileSystem/File
Version 1.1: http://[thruWebServer]/REST/1.1/FileSystem/File
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 8
3 Thru REST Services API Security
3.1 Access Signature (HTTP Header)
Access to the Thru REST API is secured through the usage of session identifier provided as part of the request header. This session identifier should be received from the Authenticator service (see below). All interactions with Thru REST Services API should take place over HTTPS. However some actions that do not require security mechanisms should be available over HTTP.
Also session identifier allows the API to identify the caller and enforce the necessary access rules to the invoked endpoint.
Note: Not all endpoints require authenticated access. If an endpoint does require authenticated access, the client needs to pass session ID in the Authorization request header:
• Authorization: SessionID
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 9
4 Exception Handling
In case of error, besides returning the standard HTTP Server error code (500), the Thru REST Services API endpoints will return more detailed information about the error in a structured format as part of response body.
4.1 Error Response
4.1.1 Error Data Transfer Object
Item Name Data Type Sample Value Comments
Message String “Invalid File ID:
12345”
Describes the type of error, indicating (when possible) which input value(s) could have caused the error
ErrorCode Integer 7001 A numeric code that identifies the type of error
Sample response(in XML)
<ErrorInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Message>Session no longer exists.</Message>
<ErrorCode>101</ErrorCode>
</ErrorInfo>
4.2 Error Codes
Each type of error generated by the Thru REST Services API has its own numeric code, which is returned in the
ErrorCode field of the ErrorInfo object. The codes can be used to determine client course of action. For the actual
error codes, check Appendix A.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 10
5 Web Service Data Specifications
5.1 API Data Types
The following primitive data types are used by the Thru REST Services API:
String: Sequence of characters in UTF-8 encoding. Empty string is used to represent a non-initialized string value
Integer: 32-bit integer number. Empty value indicates NULL-value
Long: 64-bit integer number. Empty value indicates NULL-value
Boolean: Boolean value. Possible values: True, False. Empty value indicates NULL-value
DateTime: Represents an instant in time, expressed as a date and time of day. In Thru REST services API, Empty value indicates NULL-value. DateTime is represented as a JSON string in following format /Date(ticks)/, where ticks represents the number of milliseconds since January 1, 1970 in Universal Coordinated Time (UTC). Example: “/Date(1337174868623)/”.
5.2 API Complex Data Constructions
The following complex data constructions are used by the Thru REST Services API:
Collection<T>: A collection of objects of the same type. The following XML formatting is used to pass any collection between client and server:
5.3 Session Resources
5.3.1 ThruSessionRequest Structure
ThruSessionRequest structure contains information required for the Thru user authentication.
Item Name Data Type Sample Value Comments
UserName String Test Username of the user in the system
Password String Password Password of the user
ApplicationId String 12 Application ID through which is sign-in
ClientVersion String 1 Version of the client application
Sample XML
<FileNames>
<String>Name #1</String>
<String>Another Name</String>
</FileNames>
Corresponding Object
Collection<string> FileNames;
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 11
Sample Request
UserName=Test&Password=Password&ClientVersion=1&ApplicationId=12
Sample Response
Data Transfer Object
public class ThruSessionRequest
{
public string UserName
public string Password
public string ApplicationId
public string ClientVersion
}
5.3.2 ThruPublicSession Structure
ThruPublicSession structure contains authorization information about user.
Item Name Data Type Sample Value Comments
SessionID String TOjoy3c1LyReUsXqXX/7u3+0qv
FYXGArgsZ1k0OEGhIfwB2cd365+SCM8Rs5
JOLPMD/IJJSd2Jy7IXLl5t685kgRJo0Tr
bup/VDN+25Lkenh387d4pXJzObepqO
qusnnsA4de+5r4PHfdN0
9niJtsoSOjWZ6XlEN
Unique identification value required for user authorization
UserID Integer 315KQM487N2EV Unique identification number of the user associated with SessionID value
Sample
<?xml version="1.0" encoding="utf-8"?>
<ThruPublicSession xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SessionId>PKJEkiY2UHPRyWrY3s9pmpk34iTkNSdFoNBD04jUojajM9qJXUwQULllv1R4+Olqhe5fYRo
8qHk+qDzaMOqkv4YAPX4jI6i5E4Il1+qbwl2QJ/OXfEr4MczMSXMFJIgQu5Ed5eani
kXAvIo9mzipP3hPh/LJSwWs
</SessionId>
<UserId>1Q1OBQWVHTROE</UserId>
</ThruPublicSession>
Data Transfer Object
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 12
public class ThruPublicSession
{
public string SessionID;
public int UserID;
}
5.4 File System Resources
5.4.1 ThruPublicFolderInfo Structure
ThruPublicFolderInfo structure contains information about folder in Thru file system.
Item Name Data Type Sample Value Comments
FolderID Integer 0QN8H2VKTGIWE Unique identification number for the folder in Thru file system
ParentFolderID Integer 11ETULS0966VI Unique identification number of the parent folder for the file in Thru file system.
Root folder contains NULL as a value of ParentFolderID field
Name String Admin Name of the folder
Path String FOLDERS/HOME/Admin Path to the folder in folder tree
Description String Description of the folder
Tags Collection<String> Collection of keywords associated with the current folder
Size Long 2450294218 Size of the folder
EffectivePermission Integer 254 Permissions that describe the rights of the current authenticated user over the folder. Each right is linked with the corresponding bit of the EffectivePermission field value in a binary code:
None = 0x00
Show = 0x01
Read = 0x02
Create = 0x04
Download = 0x08
Distribute = 0x010
Manage = 0x020
Modify = 0x040
Delete = 0x080
For example, full control over a folder is equal to the EffectivePermission value of 0x00FF
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 13
DateCreated DateTime /Date(1337174868623)/ Date and time when file has been created in Thru file system (UTC)
DateModified DateTime /Date(1337174868623)/ Date and time when file last has been updated (UTC)
CreatedByUserID Integer 1Q1OBQWVHTROE Unique identification number of the user that has added file to Thru file system
ModifiedByUserID Integer 1Q1OBQWVHTROE Unique identification number of the user that last accessed the file
InFavorite Boolean false Indicates is folder marked as favorite
FolderType Integer 0 0 – a regular folder
1 – root folder
2 – home folder
3 – a user’s “My Documents”
folder
4 – a user’s drop box
folder
5 – root folder for common
folders/files
6 – root folder for home
folders
Sample XML
<ThruPublicFolderInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<FolderId>0QN8H2VKTGIWE</FolderId>
<ParentFolderId>11ETULS0966VI</ParentFolderId>
<Name>Admin</Name>
<Path>FOLDERS/HOME/Admin</Path>
<Tags></Tags>
<Size>2450294218</Size>
<EffectivePermission>254</EffectivePermission>
<DateCreated>/Date(1337174868623)/</DateCreated>
<DateModified>/Date(1337174868623)/</DateModified>
<CreatedByUserId>1Q1OBQWVHTROE</CreatedByUserId>
<ModifiedByUserId>1Q1OBQWVHTROE</ModifiedByUserId>
<InFavorite>false</InFavorite>
<FolderType>0</FolderType>
</ThruPublicFolderInfo>
Data Transfer Object
public class ThruPublicFolderInfo
{
public string FolderId
public string ParentFolderId
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 14
public string Name
public string Description
public string Path
public string[] Tags
public long? Size
public int? EffectivePermission
public ThruServerDateTime DateCreated
public ThruServerDateTime DateModified
public string CreatedByUserId
public string ModifiedByUserId
public bool? InFavorite;
public int? FolderType;
}
5.4.2 ThruPublicFileInfo Structure
ThruPublicFileInfo structure contains information about file in Thru file system.
Item Name Data Type Sample Value Comments
FileID Integer 2OMFYXLA6BP9D Unique identification number for the file in Thru file system
ParentFolderID Integer 1UTXM50KW0ISP Unique identification number of the parent folder for the file in Thru file system
Name String 2.html Name of the file
Description String Description of the file
Path FOLDERS/HOME/Admin/
My Documents/2.html
Path to the file in folder tree
Tags Collection<String> Collection of keywords associated with the current folder
Size Long 198 Size of the file
EffectivePermission Integer 254 Permissions that describe the rights of the current authenticated user over the file. Each right is linked with the corresponding bit of the EffectivePermission field value in a binary code:
None = 0x00
Show = 0x01
Read = 0x02
Create = 0x04
Download = 0x08
Distribute = 0x010
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 15
Manage = 0x020
Modify = 0x040
Delete = 0x080
DateCreated DateTime /Date(1346072694480)/ Date and time when file has been created in Thru file system (UTC)
DateModified DateTime /Date(1346072694480)/ Date and time when file last has been updated (UTC)
CreatedByUserID Integer 1Q1OBQWVHTROE Unique identification number of the user that has added file to Thru file system
ModifiedByUserID Integer 1Q1OBQWVHTROE Unique identification number of the user that last accessed the file
IsQuarantined Boolean false Indicates is file has been quarantined
InFavorite
Boolean false Indicates is file marked as favorite
Sample XML
<?xml version="1.0" encoding="utf-8" ?>
<ThruPublicFileInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<FileId>2OMFYXLA6BP9D</FileId>
<ParentFolderId>1UTXM50KW0ISP</ParentFolderId>
<Name>2.html</Name>
<Path>FOLDERS/HOME/Admin/My Documents/2.html</Path>
<Tags></Tags>
<Size>198</Size>
<EffectivePermission>254</EffectivePermission>
<DateCreated>/Date(1346072694480)/</DateCreated>
<DateModified>/Date(1346072694480)/</DateModified>
<CreatedByUserId>1Q1OBQWVHTROE</CreatedByUserId>
<ModifiedByUserId>1Q1OBQWVHTROE</ModifiedByUserId>
<IsQuarantined>false</IsQuarantined>
<InFavorite>false</InFavorite>
</ThruPublicFileInfo>
Data Transfer Object
public class ThruPublicFileInfo
{
public string FileId;
public string ParentFolderId;
public string Name;
public string Description;
public string Path;
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 16
public string[] Tags;
public long? Size;
public int? EffectivePermission;
public ThruServerDateTime DateCreated;
public ThruServerDateTime DateModified;
public string CreatedByUserId;
public string ModifiedByUserId;
public bool? IsQuarantined;
public bool? InFavorite;
}
5.4.3 ThruPublicContentResult Structure
ThruPublicContentResult structure contains information about the content of the Thru folder.
Item Name Data Type Sample Value Comments
Files Collection<
ThruPublicFileInfo >
Collection of file information structures
Folders Collection<ThruPublicFolderInfo > Collection of folder information structures
Sample XML
<?xml version="1.0" encoding="utf-8" ?>
<ThruPublicContentResult xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Folders>
<ThruPublicFolderInfo>
<FolderId>16LTFSCFLMF01</FolderId>
<ParentFolderId>1UTXM50KW0ISP</ParentFolderId>
<Name>test</Name>
<Path>FOLDERS/HOME/Admin/My Documents/test</Path>
<Tags></Tags>
<Size>470968940</Size>
<ChildFoldersCount>1</ChildFoldersCount>
<ChildFilesCount>4</ChildFilesCount>
<EffectivePermission>254</EffectivePermission>
<DateCreated>/Date(1348146557730)/</DateCreated>
<DateModified>/Date(1348146557730)/</DateModified>
<CreatedByUserId>1Q1OBQWVHTROE</CreatedByUserId>
<ModifiedByUserId>1Q1OBQWVHTROE</ModifiedByUserId>
<InFavorite>false</InFavorite>
<FolderType>0</FolderType>
</ThruPublicFolderInfo>
</Folders>
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 17
<Files>
<ThruPublicFileInfo>
<FileId>2OMFYXLA6BP9D</FileId>
<ParentFolderId>1UTXM50KW0ISP</ParentFolderId>
<Name>2.html</Name>
<Path>FOLDERS/HOME/Admin/My Documents/2.html</Path>
<Tags></Tags>
<Size>198</Size>
<EffectivePermission>254</EffectivePermission>
<DateCreated>/Date(1346072694480)/</DateCreated>
<DateModified>/Date(1346072694480)/</DateModified>
<CreatedByUserId>1Q1OBQWVHTROE</CreatedByUserId>
<ModifiedByUserId>1Q1OBQWVHTROE</ModifiedByUserId>
<IsQuarantined>false</IsQuarantined>
<InFavorite>false</InFavorite>
</ThruPublicFileInfo>
</Files>
</ThruPublicContentResult>
Data Transfer Object
public class ThruPublicContentResult
{
public ThruPublicFolderInfo[] Folders;
public ThruPublicFileInfo[] Files;
}
5.5 Message Resources
5.5.1 ThruPublicMessageInfo Structure
ThruPublicMessageInfo structure contains information about Thru message.
Item Name Data Type Sample Value Comments
MessageID Integer 1HPHF1D8FF8S0 Unique identification number of the message
UserID Integer 1Q1OBQWVHTROE Unique identification number of the user that is creator of message
Subject String test Subject of the message
DateCreated DateTime /Date(1337611985780)/ Date and time when the message has been created (UTC)
DateSent DateTime /Date(1337611985780)/ Date and time when the message has been sent
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 18
(UTC)
DateExpired DateTime /Date(1357070340000)/ Date and time after which message is concerned as expired (UTC)
CollectedFlag Boolean True Indicates does message were read at least by one of recipients
PublicMessage String Public text Text of the private part of the message
PrivateMessage String Private text Text of the public part of the message
TrackingNo String T478-026-95732-36971 Number over the message is registered in Thru
RequestLogin Boolean false Flag that indicate is the message request login for access by recipient
SendByClient Boolean false Flag that indicate is the message was sent through the Thru Site or application.
NotifyFlag Boolean false Flag that indicate is the notifications must be sent.
Priority Integer 3 1 - High
2 - Low
3 - Normal
IsExpired Boolean False Flag indicate is the message is expired
ExpireNow Boolean False
MsgHtmlTemplate String Html template over a message will be created
MsgTextTemplate String Text template over a message will be created
ToRecipients Collection
<ThruPublicMessageRecipientInfo>
List of recipient email addresses
CcRecipients Collection
<ThruPublicMessageRecipientInfo>
List of Cc recipients
BccRecipients Collection
<ThruPublicMessageRecipientInfo>
List of Bcc recipients
FoldersAttached Collection<ThruPublicFolderInfo > Collection of Folder identifiers
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 19
FilesAttached Collection<ThruPublicFolderInfo > Collection of File identifiers
Sample XML
<ThruPublicMessageInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<MessageId>0A2POFJY8EB8Q</MessageId>
<UserId>1Q1OBQWVHTROE</UserId>
<Subject>subject</Subject>
<DateCreated>/Date(1352205302890)/</DateCreated>
<DateSent></DateSent>
<DateExpired>/Date(1353069302683)/</DateExpired>
<CollectedFlag>false</CollectedFlag>
<PublicMessage>body public</PublicMessage>
<PrivateMessage>body private</PrivateMessage>
<TrackingNo>T478-026-61916-68489</TrackingNo>
<RequestLogin>false</RequestLogin>
<SendByClient>true</SendByClient>
<NotifyFlag>true</NotifyFlag>
<Priority>3</Priority>
<IsExpired>false</IsExpired>
<ExpireNow>false</ExpireNow>
<MsgHtmlTemplate><!DOCTYPE HTML PUBLIC "
-/W3C//DTD HTML 4.01 Transitional//EN">
<html> <body> <span><br/>
<thru:bodyToken/>
</span></body> </html></MsgHtmlTemplate>
<MsgTextTemplate>
This email includes secure access to files.
<thru:bodyToken/>
</MsgTextTemplate>
<ToRecipients>
<ThruPublicMessageRecipientInfo>
<MsgId>0A2POFJY8EB8Q</MsgId>
<RecipientId>0MS5JFHL8E7N5</RecipientId>
<RecipientEmail>[email protected]</RecipientEmail>
<Collected>false</Collected>
</ThruPublicMessageRecipientInfo>
</ToRecipients>
<CcRecipients></CcRecipients>
<BccRecipients></BccRecipients>
<FoldersAttached></FoldersAttached>
<FilesAttached></FilesAttached>
</ThruPublicMessageInfo>
Data Transfer Object
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 20
public class ThruPublicMessageInfo
{
public string MessageId
public string UserId
public string Subject
public ThruServerDateTime DateCreated
public ThruServerDateTime DateSent
public ThruServerDateTime DateExpired
public bool? CollectedFlag
public string PublicMessage
public string PrivateMessage
public string TrackingNo
public bool? RequestLogin
public bool? SendByClient
public bool? NotifyFlag
public int? Priority
public bool? IsExpired
public bool? ExpireNow
public string MsgHtmlTemplate
public string MsgTextTemplate
public ThruPublicMessageRecipientInfo[] ToRecipients
public ThruPublicMessageRecipientInfo[] CcRecipients
public ThruPublicMessageRecipientInfo[] BccRecipients
public ThruPublicFolderInfo[] FoldersAttached
public ThruPublicFileInfo[] FilesAttached
}
5.5.2 ThruPublicMessagesListResult Structure
ThruPublicMessagesListResult structure contains collection of Thru messages.
Item Name Data Type Sample Value Comments
Messages Collection<ThruPublicMessageInfo > Collection of Messages
Sample XML
<ThruPublicMessagesListResult xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Messages>
<ThruPublicMessageInfo>
<MessageId>1R6NE5OZ8QHXA</MessageId>
<UserId>1Q1OBQWVHTROE</UserId>
<Subject>qsdasdfasd</Subject>
<DateCreated>/Date(1337718371363)/</DateCreated>
<DateSent>/Date(1337718371363)/</DateSent>
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 21
<DateExpired>/Date(1337975940000)/</DateExpired>
<CollectedFlag>true</CollectedFlag>
<PublicMessage></PublicMessage>
<PrivateMessage></PrivateMessage>
<TrackingNo>T478-026-14576-91611</TrackingNo>
<RequestLogin>false</RequestLogin>
<SendByClient>false</SendByClient>
<NotifyFlag>false</NotifyFlag>
<Priority>3</Priority>
<IsExpired>true</IsExpired>
<ExpireNow>false</ExpireNow>
<ToRecipients>
<ThruPublicMessageRecipientInfo>
<MsgId>1R6NE5OZ8QHXA</MsgId>
<RecipientId>2MIMZFR1K0471</RecipientId>
<RecipientEmail>[email protected]</RecipientEmail>
<Collected>true</Collected>
</ThruPublicMessageRecipientInfo>
</ToRecipients>
<CcRecipients></CcRecipients>
<BccRecipients></BccRecipients>
<FoldersAttached></FoldersAttached>
<FilesAttached></FilesAttached>
</ThruPublicMessageInfo>
</Messages>
</ThruPublicMessagesListResult>
Data Transfer Object
public class ThruPublicMessagesListResult
{
public ThruPublicMessageInfo[] Messages
}
5.5.3 ThruPublicMessageRecipientInfo
ThruPublicMessageRecipientInfo structure contains information about recipient of Thru message.
Item Name Data Type Sample Value Comments
MsgId String 1R6NE5OZ8QHXA Unique identification number of the Thru message
RecipientId String 2MIMZFR1K0471 Unique identification number of Recipient
RecipientEmail String [email protected] Recipient e-mail
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 22
Collected Boolean true Indicates does message were read by recipient
MsgRecipientLevelPublicID String Unique identification number of recipient level
Sample XML
<ThruPublicMessageRecipientInfo>
<MsgId>1R6NE5OZ8QHXA</MsgId>
<RecipientId>2MIMZFR1K0471</RecipientId>
<RecipientEmail>[email protected]</RecipientEmail>
<Collected>true</Collected>
<MsgRecipientLevelPublicID>true</MsgRecipientLevelPublicID>
</ThruPublicMessageRecipientInfo>
Data Transfer Object
public class ThruPublicMessageRecipientInfo
{
public string MsgId
public string RecipientId
public string RecipientEmail
public bool? Collected
public string MsgRecipientLevelPublicID
}
5.6 Search Resources
5.6.1 ThruPublicSearchCriteria Structure
ThruPublicSearchCriteria structure contains criteria for the search over Thru files and folders.
Item Name Data Type Sample Value Comments
FolderID Integer 0QN8H2VKTGIWE Indicates the folder from which to start the search
NameCriteria String * String representing the search criteria for the name of Thru file system object
NameCriteriaMatchAll Boolean True Indicates whether all criteria passed in NameCriteria field should be matched
DescriptionCriteria String * String representing the search criteria for the description of Thru file system object
DescriptionCriteriaMatchAll Boolean True Indicates whether all criteria passed in DescriptionCriteria field should be matched
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 23
KeywordCriteria String 12* String representing the search criteria for the keywords of Thru file system object
KeywordCriteriaMatchAll Boolean True Indicates whether all criteria passed in KeywordCriteria field should be matched
LastModifiedByUsers Collection<String> Collection of user unique identifiers
DateLastModifiedStart DateTime Date and time when Thru file system object has been modified. Start of Range (UTC)
DateLastModifiedEnd DateTime Date and time when Thru file system object has been modified. End of Range (UTC)
Recursive Boolean True Enable/disable recursive search over folder tree
Sample
folderId=0QN8H2VKTGIWE&NameCriteria=*&
NameCriteriaMatchAll=true&DescriptionCriteria=*&
DescriptionCriteriaMatchAll=true&KeywordCriteria=12*&
KeywordCriteriaMatchAll=true&LastModifiedByUsers=&
DateLastModifiedStart=&DateLastModifiedEnd=&Recursive=true
Data Transfer Object
public class ThruPublicSearchCriteria
{
public string FolderId
public string NameCriteria
public bool NameCriteriaMatchAll
public string DescriptionCriteria
public bool DescriptionCriteriaMatchAll
public string KeywordCriteria
public bool KeywordCriteriaMatchAll
public string[] LastModifiedByUsers
public ThruServerDateTime DateLastModifiedStart
public ThruServerDateTime DateLastModifiedEnd
public bool Recursive
}
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 24
5.7 Server Resources
5.7.1 ThruPublicServerInfo Structure
ThruPublicServerInfo structure contains information about the configuration of server and its health status.
Item Name Data Type Sample Value Comments
SiteID Integer 14RD6GNEUV4ZV Identifier of the current site
Name String test.example.com Pretty name of the current site
Title String Thru Site name Title of the site
Welcome String Welcome ‘Welcome’ text of the site
Enabled Boolean True Indicate is the site enabled
Sample
<ThruPublicServerInfo xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SiteId>14RD6GNEUV4ZV</SiteId>
<Name>test.example.com</Name>
<Title>Thru Site name</Title>
<Welcome>Thru is a secure and safe application you can use to store,
organize and distribute your files. Your username determines your ability to view,
download and upload files.</Welcome>
<Enabled>true</Enabled>
</ThruPublicServerInfo>
Data Transfer Object
public class ThruPublicServerInfo
{
public string SiteId
public string Name
public string Title
public string Welcome
public bool Enabled
}
5.7.2 ThruMessageSettings Structure
ThruMessageSettings structure contains information about the configuration of Thru messages.
Item Name Data Type Sample Value Comments
SeparateEmailsLimit Integer 1000 For tracking purposes, the system creates separate emails per recipient if the message requires a link to Thru server and request login
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 25
is turned off. This parameter prevents massive email generation.
SmtpServerRecipientLimit Integer 0 If your SMTP server has a limit, and the limit is entered here, Thru Server will block messages which exceed the limit. If the limit is NOT entered here, and a message exceeds recipient limit, SMTP server will send the message with a partial recipient list and the user will get an error message.
MsgRequestLoginType Integer 3 1 - Never (No registration for external download) 2 - Always (external download always requires registration)
3 – User Choice (request login is turned off by default but the user can turn it on when sending a message)
MsgRequestloginUserChoiceDefault Boolean False If request recipient login is 'User Choice' - turn on request login as default value for a new message.
ExpiredMsgNotificationEnabled Boolean True Enable expired message notification
WebUseMsgPwdInsteadOfRequestLogin Boolean false On the web interface, use message password instead of recipient login. This option only allowed if Request recipient login' is 'Never'.
DefaultExpirationIntervalDays Integer 10 Default expiration interval in Days
AllowSetAfterDefaultExpirationInterval Boolean False Allow to specify the message expiration interval larger than default
Sample XML
<ThruMessageSettings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SeparateEmailsLimit>1000</SeparateEmailsLimit>
<SmtpServerRecipientLimit>0</SmtpServerRecipientLimit>
<MsgRequestLoginType>3</MsgRequestLoginType>
<MsgRequestloginUserChoiceDefault>false</MsgRequestloginUserChoiceDefault>
<ExpiredMsgNotificationEnabled>true</ExpiredMsgNotificationEnabled>
<WebUseMsgPwdInsteadOfRequestLogin>false</WebUseMsgPwdInsteadOfRequestLogin>
<PrivateMessageNotificationEnabled>false</PrivateMessageNotificationEnabled>
<DefaultExpirationIntervalDays>10</DefaultExpirationIntervalDays>
<AllowSetAfterDefaultExpirationInterval>false</AllowSetAfterDefaultExpirationInter
val>
</ThruMessageSettings>
Data Transfer Object
public class ThruMessageSettings
{
public int SeparateEmailsLimit
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 26
public int SmtpServerRecipientLimit
public int MsgRequestLoginType
public bool MsgRequestloginUserChoiceDefault
public bool ExpiredMsgNotificationEnabled
public bool WebUseMsgPwdInsteadOfRequestLogin
public bool PrivateMessageNotificationEnabled
public int DefaultExpirationIntervalDays
public bool AllowSetAfterDefaultExpirationInterval
}
5.7.3 ThruPasswordSettings Structure
ThruPasswordSettings structure contains information about configuration of the password strength, expiration and lockout policies.
Item Name Data Type Sample Value Comments
AutomaticExpiration Boolean True Enable/Disable automatic password expiration
ExpirationDays Integer 10 Expiration days
ExpirationWarningNotificationDays Integer 0 Send expiration warning notification – warning days
AutomaticLoginLockout Boolean True Enable/Disable automatic login lockout
MaxLoginAttempts Integer 5 Max login attempts
LockoutDurationSeconds Integer 20 Lockout duration seconds
BlockPreviousPasswords Boolean False Do not allow reuse of previous passwords
PreviousPasswordCount Integer 3 Number of previous passwords to check
MinimumPasswordLength Integer 6 Minimum password length
RequireSpecialCharacter Boolean False At least one special character required
RequireLetter Boolean False At least one letter required
RequireDigit Boolean False At least one digit required
RequireUppercaseLetter Boolean False At least one uppercase letter required
RequireLowercaseLetter Boolean False At least one lowercase letter required
Sample XML
<ThruPasswordSettings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<AutomaticExpiration>true</AutomaticExpiration>
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 27
<ExpirationDays>10</ExpirationDays>
<ExpirationWarningNotificationDays>0</ExpirationWarningNotificationDays>
<AutomaticLoginLockout>true</AutomaticLoginLockout>
<MaxLoginAttempts>5</MaxLoginAttempts>
<LockoutDurationSeconds>20</LockoutDurationSeconds>
<BlockPreviousPasswords>false</BlockPreviousPasswords>
<PreviousPasswordCount>3</PreviousPasswordCount>
<MinimumPasswordLength>6</MinimumPasswordLength>
<RequireSpecialCharacter>false</RequireSpecialCharacter>
<RequireLetter>false</RequireLetter>
<RequireDigit>false</RequireDigit>
<RequireUppercaseLetter>false</RequireUppercaseLetter>
<RequireLowercaseLetter>false</RequireLowercaseLetter>
</ThruPasswordSettings>
Data Transfer Object
public class ThruPasswordSettings
{
public bool? AutomaticExpiration
public int? ExpirationDays
public int? ExpirationWarningNotificationDays
public bool? AutomaticLoginLockout
public int? MaxLoginAttempts
public int? LockoutDurationSeconds
public bool? BlockPreviousPasswords
public int? PreviousPasswordCount
public int? MinimumPasswordLength
public bool? RequireSpecialCharacter
public bool? RequireLetter
public bool? RequireDigit
public bool? RequireUppercaseLetter
public bool? RequireLowercaseLetter
}
5.7.4 ThruUploadSettings Structure
ThruUploadSettings structure contains information of upload settings.
Item Name Data Type Sample Value Comments
UploadAppletBatchMaxCount Integer 0 The maximum number of files uploaded in batch by the applet to the server in a single HTTP request. To indicate that there is no limit, use the value 0.
UploadAppletChunkCount Integer 20 The maximum number of chunks to divide a file to be uploaded by the applet, before we start
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 28
increasing the chunk size from the minimum size.
UploadAppletChunkMaxSizeMb Integer 100 The maximum size (in Megabytes) of a file chunk uploaded by the applet to the server.
UploadAppletChunkMinSizeMb Integer 60 The minimum size (in Megabytes) of a file chunk uploaded by the applet to the server.
UploadAppletDeleteOnCancelDefault Boolean False Indicates whether the default behavior for the applet on an upload cancellation is to delete partially uploaded files.
UploadAppletDeleteOnCancelEnabled Boolean True Indicates whether the user can opt on the behavior for the applet on an upload cancellation. If true, user can opt; false, otherwise.
UploadAppletZippingEnabled Boolean False
UploadAppletZippingMinFileSizeKb Integer 10
Sample XML
<ThruUploadSettings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<UploadAppletBatchMaxCount>0</UploadAppletBatchMaxCount>
<UploadAppletChunkCount>20</UploadAppletChunkCount>
<UploadAppletChunkMaxSizeMb>100</UploadAppletChunkMaxSizeMb>
<UploadAppletChunkMinSizeMb>60</UploadAppletChunkMinSizeMb>
<UploadAppletDeleteOnCancelDefault>false</UploadAppletDeleteOnCancelDefault>
<UploadAppletDeleteOnCancelEnabled>true</UploadAppletDeleteOnCancelEnabled>
<UploadAppletZippingEnabled>false</UploadAppletZippingEnabled>
<UploadAppletZippingMinFileSizeKb>10</UploadAppletZippingMinFileSizeKb>
</ThruUploadSettings>
Data Transfer Object
public class ThruUploadSettings
{
public int UploadAppletBatchMaxCount
public int UploadAppletChunkCount
public int UploadAppletChunkMaxSizeMb
public int UploadAppletChunkMinSizeMb
public bool UploadAppletDeleteOnCancelDefault
public bool UploadAppletDeleteOnCancelEnabled
public bool UploadAppletZippingEnabled
public int UploadAppletZippingMinFileSizeKb
}
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 29
5.7.5 ThruMobileSettings
ThruMobileSettings structure contains information of mobile application settings.
Item Name Data Type Sample Value Comments
SessionRecheckIntervalSeconds Integer 60
EnableOpenInAnotherApplication Boolean True
LocalSessionOfflineLifetimeSeconds Integer 180
MobilePolicyUpdateIntervalSeconds Integer 300
Sample XML
<ThruMobileSettings xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<SessionRecheckIntervalSeconds>60</SessionRecheckIntervalSeconds>
<EnableOpenInAnotherApplication>true</EnableOpenInAnotherApplication>
<LocalSessionOfflineLifetimeSeconds>180</LocalSessionOfflineLifetimeSeconds>
<MobilePolicyUpdateIntervalSeconds>300</MobilePolicyUpdateIntervalSeconds>
</ThruMobileSettings>
Data Transfer Object
public class ThruMobileSettings
{
public int SessionRecheckIntervalSeconds
public bool EnableOpenInAnotherApplication
public int LocalSessionOfflineLifetimeSeconds
public int MobilePolicyUpdateIntervalSeconds
}
5.8 System Log Resources
5.8.1 ThruPublicSystemLogOperation
ThruPublicSystemLogOperation structure contains information operation that will be logged in Thru.
Item Name Data Type Sample Value Comments
LogOperationId String Operation Id that is assigned for request operation
OperationType Integer MobileOpenFileInExternalApplication = 0x4000000
FolderId String Identifier of the folder in Thru file system
FileId String Identifier of the file in Thru file system
MobileReceiverAppName String Mobile application name
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 30
Sample
Request:
OperationType=67108864&FileId=30FZAAT6ULN30&MobileReceiverAppName=test
Response:
<ThruPublicSystemLogOperation xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<LogOperationId>1UEVYEHGF7GVW</LogOperationId>
<OperationType>67108864</OperationType>
<FileId>30FZAAT6ULN30</FileId>
<MobileReceiverAppName>test</MobileReceiverAppName>
</ThruPublicSystemLogOperation>
Data Transfer Object
public class ThruPublicSystemLogOperation
{
public string LogOperationId
public int OperationType
public string FolderId
public string FileId
public string MobileReceiverAppName
}
5.9 Ticket Resource
5.9.1 ThruTicketInfo Structure
ThruTicketInfo structure contains email fields
Item Name Data Type Sample Value Comments
Subject String Subject Subject text
Body String Message Body text
Sample
Subject=test&Body=message
Data Transfer Object
public class ThruTicketInfo
{
public string Subject
public string Body
}
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 31
5.10 User Resources
5.10.1 ThruPublicUserInfo Structure
ThruPublicUserInfo structure contains information about user of Thru.
Item Name Data Type Sample Value Comments
UserId String 1Q1OBQWVHTROE Identifier of user in Thru
Name String admin User name that is used for sign-in in Thru
DomainUsername String If user is in domain, this field represent it domain name
FirstName String Ad User’s first name
LastName String Test User’s last name
FullName String Ad Test User’s full name
Email String [email protected] User’s e-mail address
Phone String User’s phone number
CompanyName String Company name
Role Integer 5 User’s role on Thru:
None = 0,
Guest = 1,
Recipient = 2,
Member = 3,
Manager = 4,
Administrator = 5,
System = 6
DateCreated DateTime /Date(1337174868567)/ User’s date create (UTC)
DateModified DateTime /Date(1351871161613)/ User’s last date modify (UTC)
CreatedByUserId String Identifier of the user that is create the specified user
ModifiedByUserId String 2T5LRH8F1R2QK Identifier of the user that is modify the specified user
DateLastPasswordChanged DateTime /Date(1343838136630)/ The date of the last password modification
PasswordNeverExpires Boolean True Flag indicate is the user password is never expires
Sample XML
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 32
<ThruPublicUserInfo xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<UserId>1Q1OBQWVHTROE</UserId>
<Name>admin</Name>
<FirstName>Ad</FirstName>
<LastName>3</LastName>
<FullName>Ad 3</FullName>
<Email>[email protected]</Email>
<Phone></Phone>
<CompanyName></CompanyName>
<Role>5</Role>
<DateCreated>/Date(1337174868567)/</DateCreated>
<DateModified>/Date(1351871161613)/</DateModified>
<ModifiedByUserId>2T5LRH8F1R2QK</ModifiedByUserId>
<DateLastPasswordChanged>/Date(1343838136630)/</DateLastPasswordChanged>
<PasswordNeverExpires>true</PasswordNeverExpires>
</ThruPublicUserInfo>
Data Transfer Object
public class ThruPublicUserInfo
{
public string UserId
public string Name
public string DomainUsername
public string FirstName
public string LastName
public string FullName
public string Email
public string Phone
public string CompanyName
public int Role
public ThruServerDateTime DateCreated
public ThruServerDateTime DateModified
public string CreatedByUserId
public string ModifiedByUserId
public ThruServerDateTime DateLastPasswordChanged
public bool PasswordNeverExpires
}
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 33
5.10.2 ThruPasswordInfo Structure
ThruPasswordInfo structure contains information that is required for password change.
Item Name Data Type Sample Value Comments
OldPassword String password Current user password
NewPassword String _password1 New password that is required to set
ConfirmPassword String _password1 Confirmation of the New password field
Sample
OldPassword=password&NewPassword=_password1&ConfirmPassword=_password1
Data Transfer Object
public class ThruPasswordInfo
{
public string OldPassword
public string NewPassword
public string ConfirmPassword
}
5.11 Service Resources
5.11.1 ThruServiceVersion Structure
ThruServiceVersion structure contains information about versions of specific REST service in the ThruServer.
Item Name Data Type Sample Value Comments
ServiceName String FileSystem Service name
SupportedVersions String 1.0 Service version
Sample
<ThruServiceVersion>
<ServiceName>FileSystem</ServiceName>
<SupportedVersions>
<string>1.0</string>
</SupportedVersions>
</ThruServiceVersion>
Data Transfer Object
public class ThruServiceVersion
{
public string ServiceName
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 34
public string[] SupportedVersions
}
5.11.2 ThruServiceVersionsResult Structure
ThruServiceVersionsResult structure contains information about versions of REST services in the ThruServer.
Item Name Data Type Sample Value Comments
ServiceVersions Collection<ThruServiceVersion > REST Services
Sample
<ThruServiceVersionsResult xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<ServiceVersions>
<ThruServiceVersion>
<ServiceName>Authentication</ServiceName>
<SupportedVersions>
<string>1.0</string>
</SupportedVersions>
</ThruServiceVersion>
<ThruServiceVersion>
<ServiceName>FileSystem</ServiceName>
<SupportedVersions>
<string>1.0</string>
</SupportedVersions>
</ThruServiceVersion>
<ThruServiceVersion>
<ServiceName>Message</ServiceName>
<SupportedVersions>
<string>1.0</string>
</SupportedVersions>
</ThruServiceVersion>
<ThruServiceVersion>
<ServiceName>Search</ServiceName>
<SupportedVersions>
<string>1.0</string>
</SupportedVersions>
</ThruServiceVersion>
<ThruServiceVersion>
<ServiceName>Favorites</ServiceName>
<SupportedVersions>
<string>1.0</string>
</SupportedVersions>
</ThruServiceVersion>
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 35
<ThruServiceVersion>
<ServiceName>Server</ServiceName>
<SupportedVersions>
<string>1.0</string>
</SupportedVersions>
</ThruServiceVersion>
<ThruServiceVersion>
<ServiceName>Ticket</ServiceName>
<SupportedVersions>
<string>1.0</string>
</SupportedVersions>
</ThruServiceVersion>
<ThruServiceVersion>
<ServiceName>SystemLog</ServiceName>
<SupportedVersions>
<string>1.0</string>
</SupportedVersions>
</ThruServiceVersion>
<ThruServiceVersion>
<ServiceName>User</ServiceName>
<SupportedVersions>
<string>1.0</string>
</SupportedVersions>
</ThruServiceVersion>
</ServiceVersions>
</ThruServiceVersionsResult>
Data Transfer Object
public class ThruServiceVersionsResult
{
public ThruServiceVersion[] ServiceVersions
}
5.12 Server Version Resources
5.12.1 ThruServerVersion Structure
ThruServerVersion structure contains information about version of ThruServer.
Item Name Data Type Sample Value Comments
Major Integer 7 Major version
Minor Integer 8 Minor version
Buildnumber Integer 23 Build number
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 36
Suffix String 1.1.2 Suffix, addition version identificator. This field can be empty.
Revision Integer 11234 Revision number
Sample
<ThruServerVersion>
<Major>7</Major>
<Minor>8</Minor>
<Buildnumber>23</Buildnumber>
<Suffix></Suffix>
<Revision>12714</Revision>
</ThruServerVersion>
Data Transfer Object
public class ThruServerVersion
{
public int Major {get, set; }
public int Minor { get, set; }
public int Buildnumber { get, set; }
public string Suffix { get; set; }
public int Revision {get, set; }
}
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 37
6 Web Services
6.1 Authentication Service
6.1.1 POST New Session Object
Url [ThruWebServer]/REST/[version]/Session
Verb POST
Required HTTP Headers Accept: (application/xml or application/json), Device_UUID (any unique identifier for the client device is required)
Description Verify user credentials and authenticate Thru user in the system
Request Body ThruSessionRequest object
Return Data Object ThruPublicSession object
Invocation Scenario(s) Verify customer credentials
Authenticate customer
Remarks Example request: UserName=admin&Password=adminadmin&
ClientVersion=1&ApplicationId=12
6.1.2 DELETE Existing Session Object
Url [ThruWebServer]/REST/[version]/Session
Verb DELETE
Required HTTP Headers Accept: (application/xml or application/json)
Description Logs out Thru customer from the system.
Request Body None
Return Data Object None
Invocation Scenario(s) Expire session object
Logs out customer from the system
Remarks
6.1.3 CHECK Existing Session Object
Url [ThruWebServer]/REST/[version]/Session
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 38
Description Check if customer is authenticated.
Request Body None
Return Data Object None
Invocation Scenario(s) Check session object
Remarks
6.2 File System Service
6.2.1 POST New Folder Information
Url [ThruWebServer]/REST/[version]/FileSystem/Folder
Verb POST
Required HTTP Headers Accept: (application/xml or application/json)
Description Creates a new folder in Thru file system
Request Body ThruPublicFolderInfo object
Return Data Object Updated ThruPublicFolderInfo object
Invocation Scenario(s) Create a new folder
Remarks Example request: Name=New+Folder&ParentFolderId=1UTXM50KW0ISP&
Description=Description&Tags%5B%5D=567&Tags%5B%5D=897
6.2.2 GET Existing Folder Information
Url [ThruWebServer]/REST/[version]/FileSystem/Folder/[FolderId]
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a folder information based on the provided ID
Request Body None
Return Data Object ThruPublicFolderInfo object
Invocation Scenario(s) Get a folder information in order to fulfill it
Remarks All returned dates are in UTC.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 39
6.2.3 PUT Updated Folder Information
Url [ThruWebServer]/REST/[version]/FileSystem/Folder/[FolderId]
Verb PUT
Required HTTP Headers Accept: (application/xml or application/json)
Content-Type: (application/xml or application/json)
Description Updates folder information based on the provided information. Information should be passed
in the body as a serialized representation of the ThruPublicFolderInfo DTO.
Request Body ThruPublicFolderInfo object
Return Data Object Updated ThruPublicFolderInfo object
Invocation Scenario(s) Renaming folder
Move folder and its content to another folder
Remarks Value of the FolderID field in the posted ThruPublicFileInfo DTO should reference to the existing and non-deleted folder. Otherwise, exception will be thrown .
Not all properties of ThruPublicFolderInfo can be modified:
Name
ParentFolderID
Description
Keywords
The following properties should not be provided; if provided, their values will be ignored:
FolderID
EffectivePermission
DateCreated
DateModified
CreatedByUserID
ModifiedByUserID
Exception will be thrown in case current user doesn’t have a right to do such modifications
ModifiedByUserID field of the folder will be updated if the statement succeeds
After successful processing of the command updated ThruPublicFolderInfo object will be
returned
Example request: folderId=3V45C8UTHL0A3&Name=&ParentFolderId=&
Description=New+Description&Tags%5B%5D=
6.2.4 DELETE Existing Folder
Url [ThruWebServer]/REST/[version]/FileSystem/Folder/[FolderId]
Verb DELETE
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 40
Required HTTP Headers Accept: (application/xml or application/json)
Description Deletes folder and its content based on the provided information. No additional data should be passed on the request body
Request Body None
Return Data Object None
Invocation Scenario(s) Mark folder and all underlying files and folders as deleted
Remarks The folder could be restored later by administrator based on the Thru server configuration
6.2.5 GET Home Folder Information
Url [ThruWebServer]/REST/[version]/FileSystem/Home
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a home folder information of the authenticated user
Request Body None
Return Data Object ThruPublicFolderInfo object
Invocation Scenario(s) Get a home folder information of the authenticated user
Remarks All returned dates are in UTC.
6.2.6 GET List of Files and Folders Inside a Home Folder
Url [ThruWebServer]/REST/[version]/FileSystem/Home/Content
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of file and folder information structures based on the home folder information of the authenticated user.
Request Body None
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Get a full content of the folder
Remarks
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 41
6.2.7 GET List of Files Inside a Home Folder
Url [ThruWebServer]/REST/[version]/FileSystem/Home/Content/Files
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of file information structures based on the home folder information of the authenticated user.
Request Body None
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Get files in the folder
Remarks
6.2.8 GET List of Folders Inside a Home Folder
Url [ThruWebServer]/REST/[version]/FileSystem/Home/Content/Folders
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of folder information structures based on the home folder information of the authenticated user.
Request Body None
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Get folders in the folder
Remarks
6.2.9 GET Root Folder Information
Url [ThruWebServer]/REST/[version]/FileSystem/Root
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a root folder information of the authenticated user
Request Body None
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 42
Return Data Object ThruPublicFolderInfo object
Invocation Scenario(s) Get information of the root folder
Remarks All returned dates are in UTC.
6.2.10 GET List of Files and Folders Inside a Root Folder
Url [ThruWebServer]/REST/[version]/FileSystem/Root/Content
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of file and folder information structures based on the root folder information of the authenticated user.
Request Body None
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Get a full content of the folder
Remarks
6.2.11 GET List of Files Inside a Root Folder
Url [ThruWebServer]/REST/[version]/FileSystem/Root/Content/Files
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of file information structures based on the root folder information of the authenticated user.
Request Body None
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Get files in the folder
Remarks
6.2.12 GET List of Folders Inside a Root Folder
Url [ThruWebServer]/REST/[version]/FileSystem/Root/Content/Folders
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 43
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of folder information structures based on the root folder information of the authenticated user.
Request Body None
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Get folders in the folder
Remarks
6.2.13 GET List of Files and Folders Inside a Folder
Url [ThruWebServer]/REST/[version]/FileSystem/Folder/[FolderId]/Content
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of file and folder information structures based on the provided parent folder ID.
Request Body None
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Get a full content of the folder
Remarks
6.2.14 GET List of Files Inside a Folder
Url [ThruWebServer]/REST/[version]/FileSystem/Folder/[folderId]/Content/Files
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of file information structures based on the provided parent folder ID.
Request Body None
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Get files in the folder
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 44
Remarks
6.2.15 GET List of Folders Inside a Folder
Url [ThruWebServer]/REST/[version]/FileSystem/ Folder/[folderId]/Content/Folders
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of folder information structures based on the provided parent folder ID.
Request Body None
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Get folders in the folder
Remarks
6.2.16 GET Existing File Information
Url [ThruWebServer]/REST/[version]/FileSystem/File/[FileId]
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a file information based on the provided ID
Request Body None
Return Data Object
ThruPublicFileInfo object
Invocation Scenario(s) Get a file information in order to fulfill it
Remarks All returned dates are in UTC.
6.2.17 PUT Updated File Information
Url [ThruWebServer]/REST/[version]/FileSystem/File/[FileId]
Verb PUT
Required HTTP Headers Accept: (application/xml or application/json)
Description Updates file information based on the provided information. Information should be passed in
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 45
the body as a serialized representation of the ThruPublicFileInfo DTO
Request Body
ThruPublicFileInfo object
Return Data Object Updated ThruPublicFileInfo object
Invocation Scenario(s) Renaming file
Move file to another folder
Remarks Value of the FileID field in the posted ThruPublicFileInfo DTO should reference to the existing, non-deleted, non-quarantined file. Otherwise, exception will be thrown
Not all properties of
ThruPublicFileInfo can be modified:
Name
ParentFolderID
Description
Keywords
ParentFolderID
The following properties should not be provided; if provided, their values will be ignored:
Size
DateCreated
DateModified
CreatedByUserID
ModifiedByUserID
IsQuarantined
ModifiedByUserID field of the file will be updated if the statement succeeded
After successful processing of the command updated
ThruPublicFileInfo object will be returned
6.2.18 DELETE Existing File
Url [ThruWebServer]/REST/[version]/FileSystem/File/[FileId]
Verb DELETE
Required HTTP Headers Accept: (application/xml or application/json)
Description Deletes file based on the provided information. No additional data should be passed on the request body.
Request Body None
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 46
Return Data Object None
Invocation Scenario(s) Mark file whose ID is specified in URL as deleted
Remarks Possibly later this file can be restored by administrator based on the Thru server configuration
6.3 Message Service
6.3.1 POST New Thru Message
Url [ThruWebServer]/REST/[version]/Message
Verb POST
Required HTTP Headers Accept: (application/xml or application/json)
Description Creates Thru message according to ThruPublicMessageInfo structure passed in HTTP
request
Request Body ThruPublicMessageInfo object
Return Data Object Updated ThruPublicMessageInfo object
Invocation Scenario(s) Send one or more files and folders to recipients
Send private message to recipients
Remarks ToRecipients, CcRecipients, BccRecipients fields in ThruPublicMessageInfo should be
present in request as a string array. These fields will bind to required structure on server side. DateExpired must be converted to UTC.
Example POST parameters: BccRecipients[][email protected]
BccRecipients[][email protected]
CcRecipients[][email protected]
CcRecipients[][email protected]
DateExpired=
FilesAttached[]=
FoldersAttached[]=
NotifyFlag=
Priority=3
PrivateMessage=body private
PublicMessage=body public
RequestLogin=false
SendByClient=true
Subject=subject
ToRecipients[][email protected]
ToRecipients[][email protected]
UserPassword=
1 To-recipient should be provided at least.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 47
DateExpired must be converted to UTC. If SendByClient is true, after calling this method the client must:
1. send email notification and call the REST method ‘completeMessage‘ which sets message’s DateSent.
2. Or call the REST method ‘discardMessage’ to cancel the creation of ‘distribution’ object on the server. Created by this method message will be deleted on the server.
The returned ThruPublicMessageInfo contains ‘MsgHtmlTemplate’ parameter which
must be parsed by the client. The token <thru:bodyToken/> must be replaced with the public message. The token <thru:passwordToken/> (if exists) must be replaced with the field MsgRecipientLevelPublicID of the first To recipient.
6.3.2 GET Existing Thru Message
Url [ThruWebServer]/REST/[version]/Message/[MessageId]
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves message information based on the provided ID.
Request Body None
Return Data Object ThruPublicMessageInfo object
Invocation Scenario(s) Get a message in the Thru server
Remarks All returned dates are in UTC.
6.3.3 DELETE Existing Thru Message
Url [ThruWebServer]/REST/[version]/Message/[MessageId]
Verb DELETE
Required HTTP Headers Accept: (application/xml or application/json)
Description Deletes message based on the provided information. No additional data should be passed on the request body.
Request Body None
Return Data Object None
Invocation Scenario(s) Mark message whose ID is specified in URL as deleted
Remarks
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 48
6.3.4 PUT Updated Thru Message
Url [ThruWebServer]/REST/[version]/Message/[MessageId]
Verb PUT
Required HTTP Headers Accept: (application/xml or application/json)
Content-Type: (application/xml or application/json)
Description Updates message information based on the provided information. Information should be
passed in the body as a serialized representation of the ThruPublicMessageInfo DTO
Request Body ThruPublicMessageInfo object
Return Data Object Updated ThruPublicMessageInfo object
Invocation Scenario(s) Delete attached folders
Delete attached files
Delete recipients from the To, Cc, Bcc
Change expired date
Expire message now
Remarks Value of the MessageID field in the posted ThruPublicMessageInfo DTO should reference
to the existing, non-deleted message. Otherwise, exception will be thrown.
Not all properties of ThruPublicMessageInfo can be modified:
DateExpired
ExpireNow
ToRecipients, CcRecipients, BccRecipients
FoldersAttached, FilesAttached
DateExpired must be converted to UTC.
Recipients to delete must be provided in ToRecipients field. They will be deleted from To, Cc and Bcc lists.
If provided, the values of the following fields are ignored:
Subject
Priority
PublicMessage
PrivateMessage
CollectedFlag
RequestLogin
SendByClient
DateCreated
DateSent
After successful processing of the command updated
ThruPublicFileInfo object will be returned.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 49
6.3.5 PUT Discard Thru Message
Url [ThruWebServer]/REST/[version]/Message/Discard/[MessageId]
Verb PUT
Required HTTP Headers Accept: (application/xml or application/json)
Description Discard message based on the provided information. No additional data should be passed on the request body.
Request Body None
Return Data Object None
Invocation Scenario(s) Mark message that’s ID is specified in URL as deleted
Remarks This method can be called only after the method ‘New Thru message’ is called
6.3.6 PUT Complete Thru Message
Url [ThruWebServer]/REST/[version]/Message/Complete/[MessageId]
Verb PUT
Required HTTP Headers Accept: (application/xml or application/json)
Description Complete message based on the provided information. No additional data should be passed on the request body.
Request Body None
Return Data Object ThruPublicMessageInfo object
Invocation Scenario(s) Mark message that’s ID is specified in URL as completed.
Remarks This method can be called only after the method ‘New Thru message’ is called
6.3.7 GET SentThru List
Url [ThruWebServer]/REST/[version]/Message/Content/[skip]/[take]
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Get list of the sent messages. Attachments are not included in returned data object.
Request Body None
Return Data Object ThruPublicMessageInfo object
Invocation Scenario(s) Search over all Thru messages available for the current authenticated user.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 50
Attachments are not included in result, use GET Existing Thru Message.
Optional:
1. Skip custom number of messages.
2. Take custom number of messages.
Remarks
6.3.8 POST Project Message Storage
Url [ThruWebServer]/REST/[version]/Message/Storage/[type]
Verb POST
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a folder information of the message storage.
Request Body “Subject”: <subject> in case of Type is set “Days”. Current version of this method supports only one type=‘Days.’
Return Data Object ThruPublicMessageInfo object
Invocation Scenario(s) Find or if not exist create folder for message storage.
Optional: type of the folder name.
Remarks
6.4 Search Service
6.4.1 POST Find All Thru Files and Folders by Search Criteria
Url [ThruWebServer]/REST/[version]/Search/[Skip]/[Take]
Verb POST
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of folder and file structures based on the provided search criteria structure.
Request Body ThruPublicSearchCriteria object
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Search over all Thru files and folders available to the current authenticated user.
Remarks NameCriteria, DescriptionCriteria, KeywordCriteria are automatically wrapped by the ‘*’ if not contains it as part of criteria. For ex: “text” -> “*text*”, but “tex*t” -> “tex*t”
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 51
6.4.2 POST Find All Thru Folders by Search Criteria
Url [ThruWebServer]/REST/[version]/Search/Folders/[Skip]/[Take]
Verb POST
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of folder structures based on provided search criteria structure.
Request Body ThruPublicSearchCriteria object
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Search over all Thru folders available to the current authenticated user.
Remarks
ThruPublicContentResult always contain null for
ThruPublicFileInfo
NameCriteria, DescriptionCriteria, KeywordCriteria are automatically wrapped by the ‘*’ if not contains it as part of criteria. For ex: “text” -> “*text*”, but “tex*t” -> “tex*t”
6.4.3 POST Find All Thru Files by Search Criteria
Url [ThruWebServer]/REST/[version]/Search/Files/[Skip]/[Take]
Verb POST
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of files structures based on the provided search criteria structure.
Request Body ThruPublicSearchCriteria object
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Search over all Thru files available to the current authenticated user.
Remarks
ThruPublicContentResult always contain null for ThruPublicFolderInfo
NameCriteria, DescriptionCriteria, KeywordCriteria are automatically wrapped by the ‘*’ if not contains it as part of criteria. For ex: “text” -> “*text*”, but “tex*t” -> “tex*t”
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 52
6.5 Server Service
6.5.1 GET Server Information
Url [ThruWebServer]/REST/[version]/Server/Info
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves information about current server.
Request Body None
Return Data Object ThruPublicServerInfo object
Invocation Scenario(s) Get file information in order to fulfill it.
Remarks
6.5.2 GET Message Settings
Url [ThruWebServer]/REST/[version]/Server/MessageSettings
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves information about message settings in the server.
Request Body None
Return Data Object ThruMessageSettings object
Invocation Scenario(s) Get information about message settings in order to fulfill it.
Remarks
6.5.3 GET Password Settings
Url [ThruWebServer]/REST/[version]/Server/PasswordSettings
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves information about password settings in the server
Request Body None
Return Data Object ThruPasswordSettings object
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 53
Invocation Scenario(s) Get information about password settings in order to fulfill it.
Remarks
6.5.4 GET Upload Settings
Url [ThruWebServer]/REST/[version]/Server/UploadSettings
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves information about upload settings in the server.
Request Body None
Return Data Object ThruUploadSettings object
Invocation Scenario(s) Get information about upload settings in the server.
Remarks
6.5.5 GET Mobile settings
Url [ThruWebServer]/REST/[version]/Server/MobileSettings
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves information about mobile settings in the server.
Request Body None
Return Data Object ThruMobileSettings object
Invocation Scenario(s) Get information about mobile settings in the server.
Remarks
6.6 Favorites Service
6.6.1 PUT Folder to Favorites
Url [ThruWebServer]/REST/[version]/Favorites/Folder/[FolderId]
Verb PUT
Required HTTP Headers Accept: (application/xml or application/json)
Description Add folder with the specified id to favorites.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 54
Request Body None
Return Data Object None
Invocation Scenario(s) Mark folder whose ID is specified in URL as favorite
Remarks
6.6.2 DELETE Folder from Favorites
Url [ThruWebServer]/REST/[version]/Favorites/Folder/[FolderId]
Verb DELETE
Required HTTP Headers Accept: (application/xml or application/json)
Description Remove folder with the specified ID from favorites.
Request Body None
Return Data Object None
Invocation Scenario(s) Remove folder whose ID is specified in URL from favorites
Remarks
6.6.3 PUT File to Favorites
Url [ThruWebServer]/REST/[version]/Favorites/File/[FileId]
Verb PUT
Required HTTP Headers Accept: (application/xml or application/json)
Description Add file with the specified ID to favorites.
Request Body None
Return Data Object None
Invocation Scenario(s) Mark file whose ID is specified in URL as favorite.
Remarks
6.6.4 DELETE File from Favorites
Url [ThruWebServer]/REST/[version]/Favorites/File/[FileId]
Verb DELETE
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 55
Required HTTP Headers Accept: (application/xml or application/json)
Description Remove file with the specified ID from favorites.
Request Body None
Return Data Object None
Invocation Scenario(s) Remove file whose ID is specified in URL from favorites.
Remarks
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 56
6.6.5 GET All Content in Favorites
Url [ThruWebServer]/REST/[version]/Favorites/Content
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of file and folder information structures marked as favorites. Result can be filtered by options.
Request Body
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Get a full content in favorites.
Get files in favorites.
Get folders in favorites.
Remarks
6.6.6 GET Files in Favorites
Url [ThruWebServer]/REST/[version]/Favorites/Content/Files
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of file information structures marked as favorites. Result can be filtered by options.
Request Body
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Get files in favorites.
Remarks
6.6.7 GET Folders in Favorites
Url [ThruWebServer]/REST/[version]/Favorites/Content/Folders
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Retrieves a collection of folder information structures marked as favorites. Result can be filtered by options.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 57
Request Body
Return Data Object
ThruPublicContentResult object
Invocation Scenario(s) Get folders in favorites.
Remarks
6.7 Service Versions Service
6.7.1 GET Information about Service Versions
Url [ThruWebServer]/REST/[version]/ServiceVersions
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Description Gets information about versions of REST services in the ThruServer .
Request Body None
Return Data Object ThruServiceVersion object
Invocation Scenario(s) Get list of services and their versions.
Remarks
6.8 System Log Service
6.8.1 POST System Log Operation
Url [ThruWebServer]/REST/[version]/SystemLog/[operationId]
Verb POST
Required HTTP Headers Accept: (application/xml or application/json)
Security Header Required
Description Add new log operation based on the provided ThruPublicSystemLogOperation structure.
Request Body ThruPublicSystemLogOperation object
Return Data Object ThruPublicSystemLogOperation object with system log operation id
Invocation Scenario(s) Add new system log data.
Remarks
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 58
6.9 Ticket Service
6.9.1 POST New Ticket
Url [ThruWebServer]/REST/[version]/Ticket
Verb POST
Required HTTP Headers Accept: (application/xml or application/json)
Security Header Required
Description Send ticket based on the provided information.
Request Body ThruTicketInfo object
Return Data Object None
Invocation Scenario(s) Send email to reseller.
Remarks
6.10 User Service
6.10.1 GET User Information
Url [ThruWebServer]/REST/[version]/User/Info
Verb GET
Required HTTP Headers Accept: (application/xml or application/json)
Security Header Required
Description Get information about currently logged user.
Request Body None
Return Data Object ThruPublicUserInfo object
Invocation Scenario(s) Get information about user.
Remarks
6.10.2 PUT New Password for the User
Url [ThruWebServer]/REST/[version]/User/Password
Verb PUT
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 59
Required HTTP Headers Accept: (application/xml or application/json)
Security Header Required
Description Set new password for the user.
Request Body ThruPasswordInfo object
Return Data Object None
Invocation Scenario(s) Set new password.
Remarks
6.11 Server Version Service
6.11.1 GET Information About Server Version
Url [ThruWebServer]/REST/ServerVersion
Verb GET
Required HTTP Headers
Accept: (application/xml or application/json)
Description Gets information about version of Thru Server .
Request Body None
Return Data Object ThruServerVersion Structure object
Invocation Scenario(s)
Get version.
Remarks Example:
Server version 7.8.13.0.3.12312
Return:
Major: 7
Minor: 8
Buildnumber: 13
Suffix: 0.3
Revision: 12312
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 60
7 Programmatic File and Folder Transfers.
7.1 Downloading.
File and folder downloads from Thru server should be implemented via HTTP GET to a URL servername/download.aspx, the URL requires authentication via SessionID for existing user session.
External application that connects to a Thru server should browse to a Thru folder that contains required files using web services. Once in the right folder, Web call GetFiles returns an array of FTHFileData objects, each object contains FileID for the files stored in requested parent folder. WS call GetFolders returns an array of FTHFolderData objects, each object contains FolderID for the folders stored in requested parent folder
Single File download: using HTTP library such as web client library included into .NET framework, external application issue the HTTP GET command to the URL servername/download.aspx?fileid=FileID&sessionid=SessionID , where FileID is retrieved by previous GetFiles WS call and SessionID parameter is returned by one of the Open() web service calls. In response Thru server starts writing selected file as a binary stream into HTTP client, the stream has to be saved into the local file system. It is highly recommended to open HTTPS connection to provide secure download.
Single Folder Download: using HTTP library such as web client library included into .NET framework, external application issues the HTTP GET command to the URL servername/download.aspx?folderid=FolderID&sessionid=SessionID, where FolderID is retrieved by previous GetFolders web call and SessionID parameter is returned by one of the Open() web service calls. In response Thru server creates an archive in a ZIP format that includes all subfolders of a selected folder and starts writing an archive file as a binary stream into HTTP client. The stream has to be saved into the local file. Archive file is named following the pattern foldername.zip. When external application has to download a folder, it is generally recommended to navigate down Thru folder tree and download files separately for better control at the file level, as opposed to downloading the whole folder that comes in a zipped form and has to be unzipped by a client application.
Downloading of multiple files and folders: using HTTP library such as web client library included into .NET framework, external application issue the HTTP GET command to the URL servername/download.aspx?fileid=FileID1, …FileDN& folderid=FolderID1, …FolderDN&sessionid=SessionID , where FileID1, …FileIDN is a comma-separated list of File IDs returned by a previous call to GetFiles and FolderD1, …FolderDN is a comma separated list of folder IDs returned by a previous call to GetFolders. SessionID parameter is returned by one of the Open() web service calls. In response Thru server packages requested files and folders into ZIP archive named using the pattern “THRU-XXXXXXXXXX.zip” where XXX represents random combination of hexadecimal letters and digits, and starts writing the ZIP archive as a binary stream into HTTP client. The stream has to be saved into the local file system. It is highly recommended to open HTTPS connection to provide secure download. The following values of HTTP headers are returned in all cases:
o Content-Type "application/binary"
o Content-Disposition: attachment; filename=filename.ext (to save the file under original name)
o Content-Length: <file size in bytes>
In case of error the following custom HTTP header is returned that contains an error code and message:
o "X-FTH-Error", error contents is ErrorCode and Error Message separated by pipe character: “ErrorCode | ErrorMessage”
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 61
7.2 Uploading Files and Folders via basic protocol (deprecated)
File upload is implemented by a Thru server via HTTP POST command to a URL servername/upload.aspx that requires authentication via session ID. It is recommended to use HTTPS connection for security purposes.
Size of each uploaded file is limited to 2GB. To upload the files larger than 2GB please use extended upload protocol.
HTTP POST command is used to send the parameters and upload files as part of multipart forms of the following type:
<FORM ENCTYPE="multipart/form-data" action=" servername/upload.aspx " method=post> <INPUT NAME="file" TYPE="file"> <INPUT NAME="filename0" TYPE="hidden" value=”filename.ext”> <INPUT NAME="Description0" TYPE="hidden" value=”description_here”> <INPUT NAME=" SessionID" TYPE="hidden" value=sessionID> <INPUT NAME=" folderID " TYPE="hidden" value= folderID > <INPUT NAME=" EntityCount " TYPE="hidden" value = 1> <INPUT NAME=" overwrite" TYPE="hidden" value=[1 or 0 here]> <INPUT NAME=" NoRedirect " TYPE="hidden" value=”any value here”>
File/Folder upload process can be implemented using .NET framework web client library or any other file upload library like COM objects from third-party vendors.
Upload via HTTP POST should be used in conjunction with web services to log into the server, browse to the target location and retrieve information on FileIDs and FolderIDs.
Web client library used by external application should issue HTTP POST command to the page servername/upload.aspx with the following set of fields:
‘file’ contains file body. File size is limited to 2GB due to HTTP POST implementation by the browsers.
‘filename0’ (ends with zero): name that will be given to the file in Thru server.
‘Description0’ (ends with zero): name that will be given to the file in Thru server.
‘SessionID’ should be set to current sessionID, returned by one of the Open() web service calls.
‘folderID’ should be set to id of the target parent folder where a file should be uploaded. The folderID has to be retrieved via prior calls to web services such as GetFolders or GetFolder.
“EntityCount” should be set to 1 since only one file is uploaded
“overwrite” flag equals 1 means that existing file with the same name in the same parent folder should be overwritten, if set to 0, the new file name will be versioned to name[i]
"NoRedirect" parameter has to be defined in the POST request and set to any value for web libraries that call Thru server 3
rd party applications. Please note this is mandatory parameter for external applications.
The following values of HTTP headers are returned as result of upload:
In case of successful upload:
"X-FileID0" (ends with zero) contains File ID of newly created file in Thru server.
In case of error:
"X-FTH-Error", error contents is ErrorCode and Error Message separated by pipe character: “ErrorCode | ErrorMessage”
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 62
To upload multiple files external application should repeat the file uploading process specified in for each file
To upload the folder hierarchies to Thru server, external application should use connect to Thru server using one of Open() web service calls and use call CreateFolder() to create Thru folder. Each file should be uploaded according to the process specified in 2.6.2. There is no size limit on the folder upload except for 2GB upload per each file.
7.3 Uploading of files via Extended File Upload/Download Protocol
Extended transfer protocol allows uploading of multiple files and folders in a single transaction and supports pause, resume and cleanup of partially uploaded files for data consistency. There is no limitation on the size of uploaded file since files are uploaded by the chunks.
The protocol is used by Thru connectors for Microsoft Outlook, iOS and Android applications.
Please see protocol specification in the document Thru Server Extended File Upload Download Protocol Ref x_y.docx available at Thru web site www.thruinc.com.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 63
8 File Transfer User Interface Tools
8.1 Upload Java/HTML5/HTML4 Tool and API
8.1.1 Overview
Any third party web or native application can use Thru Upload Tool to transfer files and folders of unlimited size to a Thru server with pause/resume and network recover capabilities, no coding against protocol is required. To upload files and folders 3rd party application should call a URL in the following format: https://thruservername/ExternalJavaUpload.aspx and supply parameters as specified below. Java applet displays and uploads files and folders to the target folder. If Java is not installed on the workstation, upload tool uses HTML5 or HTML4 depending on the browser capability, starting with server version 7.8.25.
8.1.2 Security Token
The API links calling the upload pop up tool can be protected from being manually copied and used by a different user under the existing SessionID.
Token based security is used to protect a call to upload tool. Token is encrypted by an application calling Thru API using a secret key shared with Thru. The token it passed to the Thru server and is decrypted using the shared key.
Security token structure for upload tool is represented in JSON with following fields:
{
“Version” ,
“FolderID”,
“Email”,
“AllowedIP”,
“TimeStamp”,
“Session”
}
Where the parameters are:
Version : version of token object. Supported value: 1. FolderID : ID of folder that is used for files/folders uploading by upload tool, returned by one of folder management API calls. Email : email of a user to record in audit records with operation. Could be different from a user account which opened a Thru server. AllowedIP : IP address allowed to perform the upload, will be checked by Thru server. If the IP address of connecting browser does not match AllowedIP, operation is blocked. TimeStamp : time of token creation, used for token validation to protect against token replay. Thru server will check that token is not beyond expiration time interval defined in Thru server. Note: Date should be strictly in the format MM/DD/YYY H:MM PM Session : unique identifier of the Thru user session received as result of Open() or OpenImmutable() call. Will be used for access control and logging purposes.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 64
Sample Token: { "Version":"1", " FolderID":"1056", "Email":"[email protected]", "AllowedIP":"64.95.64.190", "TimeStamp":"10/04/2013 11:05:11", "Session":"a2a1163e-555a-469d-bfb4-4da33980409b" }
The following methods and options should be used by calling application to encrypt the token :
Encryption algorithm: Advanced Encryption Standard (AES-256) symmetric algorithm.
Encryptor specified key: shared key in base64string format
Initialization vector (IV): shared key in base64string format
Security token for URL should use base64string format. Sample of token encryption parameters:
Encryptor specified key: AFA3wdfEuCrdFw8QaHFzN6LRXaBoCTHxcWnqNImp7g3=
Initialization vector (IV): JHnmhMkTjkl8fHqYx/l7bA==
Encrypted token in base64string format: jGldNNh7rMjT/fLL27vyQDPXUl/UjBKKfgrzLAxmopIxotP/T20Mz5J180jhG3Soqkz8bB1AV6rz3NMcyYtmm3mdo+CLeD0FDfgJZ6cw1Iqs9V+R79KsJ1mzfUKGrgQmrOq1NlosLcBtzmoVLK4+Cqkt+bkNBdYoYw8DITFkHd/VsEHCnk5pjPd89mDATyjTu4xMCXFVH20lP7tTOU75k61LLSj3X6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPIThjeO==
8.1.3 Upload Tool URL Parameters, option with no Security Token.
ThruSessionID [mandatory] : Unique identifier of the current session
ThruFolderID [mandatory] : Unique identifier of a folder on Thru server
ThruSuccessUrl [mandatory] : Browser window containing Java upload applet will be redirected to this URL on successful upload
ThruErrorReportingUrl [mandatory] : Browser window containing Java applet will be redirected to this URL on failed upload. If upload failed, server will return server error code (see below) in parameter “ThruErrorCode”. If an error occurred and ThruErrorReportingURL is not defined then server will throw an exception in the page which contains Java upload applet.
Note: the value of ThruErrorReportingUrl is not validated. You should verify it is a valid URL that does exist when integrating Thru java upload applet.
ThruFileFilter [optional] : specifies which file types can be uploaded via Java applet Format: <Description> : <extension1>, <extension2> … <extensionN> . Example: ThruFileFilter=“Zip files (*.zip, *.7z, *.tar): zip, 7z, tar” will allow upload of files with zip, 7z, tar extensions. Browsing in Add button is allowed only to the files of specified type. Drag and drop for all other file types is ignored. If parameter is not specified, all file types can be uploaded.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 65
ThruFileFilterExceptions [optional] : specifies which file types cannot be uploaded via Java applet. Format: <extension1>, <extensionX>. Example: ThruFileFilterExceptions=exe,msi,mp3 will prevent uploading of the file types exe, msi, mp3.
Note: Parameters ThruFileFilter and ThruFileFilterExceptions are mutually exclusive, only one can be used on java upload URL. If the same file extension is specified in ThruFileFilter and ThruFileFilterExceptions, the latter overrides the former.
8.1.4 Upload Tool URL Parameters, option with Security Token.
ThruFolderID [mandatory] : base64string value that represents encrypted security token
ThruSuccessUrl [mandatory] : Browser window containing Java upload applet will be redirected to this URL on successful upload
ThruErrorReportingUrl [mandatory] : Browser window containing Java applet will be redirected to this URL on failed upload. If upload failed, server will return server error code (see below) in parameter “ThruErrorCode”. If an error occurred and ThruErrorReportingURL is not defined then server will throw an exception in the page which contains Java upload applet.
Note: the value of ThruErrorReportingUrl is not validated. You should verify it is a valid URL that does exist when integrating Thru java upload applet.
ThruFileFilter [optional] : specifies which file types can be uploaded via Java applet Format: <Description> : <extension1>, <extension2> … <extensionN> . Example: ThruFileFilter=“Zip files (*.zip, *.7z, *.tar): zip, 7z, tar” will allow upload of files with zip, 7z, tar extensions. Browsing in Add button is allowed only to the files of specified type. Drag and drop for all other file types is ignored. If parameter is not specified, all file types can be uploaded.
ThruFileFilterExceptions [optional] : specifies which file types cannot be uploaded via Java applet. Format: <extension1>, <extensionX>. Example: ThruFileFilterExceptions=exe,msi,mp3 will prevent uploading of the file types exe, msi, mp3.
Note: Parameters ThruFileFilter and ThruFileFilterExceptions are mutually exclusive, only one can be used on java upload URL. If the same file extension is specified in ThruFileFilter and ThruFileFilterExceptions, the latter overrides the former.
ThruApplicationID [mandatory] : id of application for which the security token is created
8.1.5 Server Error Codes
These codes are passed as parameters to the ThruErrorReportingUrl in case any error occurs:
0 Unknown error, information is not available. 1 SessionID is not a valid Guid variable. 2 FolderID is not a valid integer variable. 3 Unknown ThruSessionID. Supplied session identifier does not exist on server 4 Folder with specified ID does not exist. 5 Upload failed. This is generic error code returned for any unknown error in upload. 6. ApplicationId is not present in URL 7. Token is invalid or expired
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 66
8.1.6 JavaScript Samples
(Session and folder ID are fictitious)
<html> <head> <script language="javascript" src="http://test.thruinc.net/Scripts/jquery-1.3.2.min.js" type="text/javascript"></script> <script language="javascript" type="text/javascript"> //sample with ThruFileFilter $(function(){ var session = '289BEE79-F1B6-4DDE-9A6B-DB5461780FCA'; var url = "https://test.thruinc.net/ExternalJavaUpload.aspx?"; url += "ThruFolderID=" + "1026"; url += "&ThruSessionID=" + session; url += "&ThruSuccessUrl=" + escape("http://someserver/ExtUpload/success.html"); url += "&ThruErrorReportingUrl=" + escape("http://someserver/ExtUpload/error.html"); url += "&ThruFileFilter=" + "Zip files (*.zip, *.7z, *.tar): zip, 7z, tar"; $("#f").attr("src", url); }); </script> </head> <body> <iframe id="f" width="800px" height="800px" src=""></iframe> </body> </html>
<html> <head> <script language="javascript" src="http://test.thruinc.net/Scripts/jquery-1.3.2.min.js" type="text/javascript"></script> <script language="javascript" type="text/javascript"> //sample with ThruFileFilterExceptions $(function(){ var session = '289BEE79-F1B6-4DDE-9A6B-DB5461780FCA'; var url = "https://test.thruinc.net/ExternalJavaUpload.aspx?"; url += "ThruFolderID=" + "1026"; url += "&ThruSessionID=" + session; url += "&ThruSuccessUrl=" + escape("http://someserver/ExtUpload/success.html"); url += "&ThruErrorReportingUrl=" + escape("http://someserver/ExtUpload/error.html"); url += "& ThruFileFilterExceptions=" + "exe,msi,mp3"; $("#f").attr("src", url); }); </script> </head> <body> <iframe id="f" width="800px" height="800px" src=""></iframe> </body> </html>
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 67
<html> <head> <script language="javascript" src="http://triton.actimind.com/Scripts/jquery-1.3.2.min.js" type="text/javascript"></script> <script language="javascript" type="text/javascript"> //sample with security token $(function(){ var session = '289BEE79-F1B6-4DDE-9A6B-DB5461780FCA'; var url = "https:// test.thruinc.net/ExternalJavaUpload?"; url += "ThruFolderID=" + " hLmrvNNh7rMjT/fLL27vyQDPXUl/UjBKKwurzLAxmopIxotP/T20Mz5J180jhG3Soqkz8bB1AV6rz3NMcyYtmm3mdo+CLeD0FDfgJZ6cw1Iqs9V+R79KsJ1mzfUKGrgQmrOq1NlosLcBtzmoVPW4+Cqkt+bkNBdYoYw8DITFkHd/VsEHCnk5pjPd89mDATyjTu4xMCXFVH20lP7tTOU75k61LLSj3X6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPITyz1Q=="; url += "&ThruSuccessUrl=" + escape("http://someserver/ExtUpload/success.html"); url += "&ThruErrorReportingUrl=" + escape("http://someserver/ExtUpload/error.html"); url += "&ThruFileFilter=" + "Zip files (*.zip, *.7z, *.tar): zip, 7z, tar"; url += "&ThruApplicationID=" + "1"; $("#f").attr("src", url); }); </script> </head> <body> <iframe id="f" width="800px" height="800px" src=""></iframe> </body> </html>
8.1.7 URL Samples
(Session and folderID are fictitious):
With file filter: http://test.thruinc.net/ExternalJavaUpload.aspx?ThruFolderID=1026&ThruSessionID=AF258C14-4425-4B30-834D-0EBD8EC55161&ThruSuccessUrl=http://www.thruinc.com&ThruErrorReportingUrl=http://www.yahoo.com&ThruFileFilter="Zip files (*.zip, *.7z, *.tar): zip, 7z, tar" With exclusion file filter: http://test.thruinc.net/ExternalJavaUpload.aspx?ThruFolderID=1026&ThruSessionID=AF258C14-4425-4B30-834D-0EBD8EC55161&ThruSuccessUrl=http://www.thruinc.com&ThruErrorReportingUrl=http://www.yahoo.com&ThruFileFilterExceptions="exe,msi,mp3” With security token: http://test.thruinc.net/ExternalJavaUpload.aspx?ThruFolderID= hLmrvNNh7rMjT/fLL27vyQDPXUl/UjBKKwurzLAxmopIxotP/T20Mz5J180jhG3Soqkz8bB1AV6rz3NMcyYtmm3mdo+CLeD0FDfgJZ6cw1Iqs9V+R79KsJ1mzfUKGrgQmrOq1NlosLcBtzmoVPW4+Cqkt+bkNBdYoYw8DITFkHd/VsEHCnk5pjPd89mDATyjTu4xMCXFVH20lP7tTOU75k61LLSj3X6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPITyz1Q==& ThruSuccessUrl=http://www.thruinc.com&ThruErrorReportingUrl=http://www.yahoo.com&ThruFileFilterExceptions="exe,msi,mp3” "&ThruApplicationID=341893067109
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 68
8.2 Java/HTML Download Tool and API
8.2.1 Overview
Any 3rd
party web or native application can use Thru Java download API to transfer files and folders from a Thru server. To download files and folders 3rd party application should call a URL in the following format: https://thruservername/ ExternalJavaDownload.aspx and supply parameters as specified below.
8.2.2 Security Token
The API links calling the download tool can be protected from being manually copied and used by a different user under the existing SessionID.
Token based security is used to protect a call to download tool. Token is encrypted by an application calling Thru API using a secret key shared with Thru. The token it passed to the Thru server and is decrypted using the shared key.
Security token structure for download tool is represented in JSON with following fields:
{
“Version” ,
“FilePublicID”,
“Email”,
“AllowedIP”,
“TimeStamp”
}
Where the parameters are:
Version : version of token object. Supported value: 1. FilePublicID: download ID of the file AccessID returned by the call RetrieveUploadInfo() Email : email of a user to record in audit records with operation. Could be different from a user account which opened a Thru server. AllowedIP : IP address allowed to perform the download, will be checked by Thru server. If the IP address of connecting browser does not match AllowedIP, operation is blocked. TimeStamp : time of token creation, used for token validation to protect against token replay. Thru server will check that token is not beyond expiration time interval defined in Thru server.
Note: Date should be strictly in the format MM/DD/YYY H:MM PM Sample Token: { "Version":"1", " FilePublicID":"0F540NC8ZAMQO", "Email":"[email protected]", "AllowedIP":"64.95.64.190", "TimeStamp":"10/04/2013 11:05:11", }
The following methods and options should be used by calling application to encrypt the token :
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 69
Encryption algorithm: Advanced Encryption Standard (AES-256) symmetric algorithm.
Encryptor specified key: shared key in base64string format
Initialization vector (IV): shared key in base64string format
Security token for URL should use base64string format. Sample of token encryption parameters:
Encryptor specified key: AFA3wdfEuCrdFw8QaHFzN6LRXaBoCTHxcWnqNImp7g3=
Initialization vector (IV): JHnmhMkTjkl8fHqYx/l7bA==
Encrypted token in base64string format: jGldNNh7rMjT/fLL27vyQDPXUl/UjBKKfgrzLAxmopIxotP/T20Mz5J180jhG3Soqkz8bB1AV6rz3NMcyYtmm3mdo+CLeD0FDfgJZ6cw1Iqs9V+R79KsJ1mzfUKGrgQmrOq1NlosLcBtzmoVLK4+Cqkt+bkNBdYoYw8DITFkHd/VsEHCnk5pjPd89mDATyjTu4xMCXFVH20lP7tTOU75k61LLSj3X6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPIThjeO==
8.2.3 Download Tool URL Parameters, option with no Security Token
ThruSessionId [mandatory] – Unique identifier of the current session.
ThruSuccessUrl [mandatory] : Browser window containing Java download applet will be redirected to this URL on successful download
ThruErrorReportingUrl [mandatory] : Browser window containing Java applet will be redirected to this URL on failed download. If download failed, server will return server error code (see below) in parameter “ThruErrorCode”. If an error occurred and ThruErrorReportingURL is not defined then server will throw an exception in the page which contains Java download applet. Note: the value of ThruErrorReportingUrl is not validated. You should verify it is a valid URL that does exist when integrating Thru java download applet.
ThruFiles [optional] – string of comma separated IDs of files to download. String format: <fileId1>,… <fileIdN> . Example: ThruFiles=“18270,18367”
ThruFolders [optional] – string of comma separated IDs of folders for download. String format: <fileId1>, <fileId2> … <fileIdN> . Example: ThruFolders=“198, 199”
Note: at least one parameter ThruFiles or ThruFolders should not be empty.
8.2.4 Download Tool URL Parameters, option with Security Token
Note: sessionID from Thru is not required of this type of download, user is not authenticated in Thru since calling application is supposed to authenticate a user.
ThruSuccessUrl [mandatory] : Browser window containing download tool will be redirected to this URL on successful download
ThruErrorReportingUrl [mandatory] : Browser window containing download tool will be redirected to this URL on failed download. If download failed, server will return server error code (see below) in parameter “ThruErrorCode”. If an error occurred and ThruErrorReportingURL is not defined then server will throw an exception in the page which contains Java download applet.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 70
Note: the value of ThruErrorReportingUrl is not validated. You should verify it is a valid URL that does exist when integrating Thru download tool.
ThruFiles [optional] : string of comma separated tokens for file for downloads, one token per file. Token is represented in base64string format . String format: <encrypted token in base64format>, < encrypted token2 in base64format > … < encrypted tokenN in base64format >
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 71
8.2.5 Server Error Codes
These codes are passed as parameters to the ThruErrorReportingUrl in case any error occurs:
0 Unknown error, information is not available. 1 SessionID is not a valid Guid variable. 2 Unknown ThruSessionID. Supplied session identifier does not exist on server 3 ThruFiles or ThruFolders contain invalid ID integer value 4 ThruFiles or ThruFolders contain ID of the file or folder that does not exist 5 ThruFiles and ThruFolders parameters are empty. Nothing to download 6 Download failed. This is generic error code returned for any unknown error in Download. 7. ApplicationId is not present in URL 8. Token is invalid or expired
8.2.6 JavaScript Samples
(Session and folder IDs are fictitious)
<html><head> <script language="javascript" src="http:// test.thrudownload.com/Scripts/jquery-1.3.2.min.js" type="text/javascript"></script> <script language="javascript" type="text/javascript"> //download by authenticated user with SessionID $(function(){ var session = “dfb039f1-4488-4c96-a2ab-085de3ecf77d”; var url = “http://test.thruinc.net/ExternalJavaDownload.aspx?”; url += "&ThruSessionID=" + session; url += "ThruFiles=" + "18370, 18366"; url += "ThruFolders=" + "198"; url += "&ThruSuccessUrl=" + escape("http://server/ExtDownload/success.html"); url += "&ThruErrorReportingUrl=" + escape("http://server/ExtDownload/error.html"); $("#f").attr("src", url); }); </script> </head> <body> <iframe id="f" width="1px" height="1px" src=""></iframe> </body> </html> <html><head> <script language="javascript" src="http:// test.thrudownload.com/Scripts/jquery-1.3.2.min.js" type="text/javascript"></script> <script language="javascript" type="text/javascript"> //download by using security token $(function(){ var session = “dfb039f1-4488-4c96-a2ab-085de3ecf77d”; var url = “http://test.thruinc.net/ExternalJavaDownload.aspx?”; url += "ThruFiles=" + "hLmrvNNh7rMjT%2ffLL27vyQDPXUl%2fUjBKKwurzLAxmopIxotP%2fT20Mz5J180jhG3Soqkz8bB1AV6rz3NMcyYtmm3mdo%2bCLeD0FDfgJZ6cw1Iqs9V%2bR79KsJ1mzfUKGrgQmrOq1NlosLcBtzmoVPW4%2bCqkt%2bbkNBdYoYw8DITFkHd%2fVsEHCnk5pjPd89mDATyjTu4xMCXFVH20lP7tTOU75k61LLSj3X6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPITyz1Q"; url += "&ThruSuccessUrl=" + escape("http://server/ExtDownload/success.html"); url += "&ThruErrorReportingUrl=" + escape("http://server/ExtDownload/error.html"); $("#f").attr("src", url); }); </script>
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 72
</head> <body> <iframe id="f" width="1px" height="1px" src=""></iframe> </body> </html>
8.2.7 URL Sample
Download using Session ID for authenticated users: http://test.thruinc.net/ExternalJavaDownload.aspx?ThruSessionID=dfb039f1-4488-4c96-a2ab-085de3ecf77d&ThruFiles=18370,18366&ThruFolders=198&ThruSuccessUrl= http://server/ExtDownload/success.html&ThruErrorReportingUrl=http://server/ExtDownload/error.html
Download using security token:
http:// test.thrudownload.com
/ExternalJavaDownload.aspx?ThruSuccessUrl=http://google.com&ThruErrorReportingUrl=http://yahoo.co
m&ThruFiles=hLmrvNNh7rMjT%2ffLL27vyQDPXUl%2fUjBKKwurzLAxmopIxotP%2fT20Mz5J180jh
G3Soqkz8bB1AV6rz3NMcyYtmm3mdo%2bCLeD0FDfgJZ6cw1Iqs9V%2bR79KsJ1mzfUKGrgQmrOq1
NlosLcBtzmoVPW4%2bCqkt%2bbkNBdYoYw8DITFkHd%2fVsEHCnk5pjPd89mDATyjTu4xMCXFVH
20lP7tTOU75k61LLSj3X6bHzCuorKcUzp7nuvxve0se9cOdFQ3TA6XH78IMGmdoOz9JgDPITyz1Q%3d
%3d&ThruApplicationID=2987490673892
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 73
Appendix A – Error Codes returned by REST API
In case of unhandled error the 90000 code will be return to client.
Error Code Error Message
7001 Invalid username.
7002 Invalid password.
7003 Invalid application id.
7004 Invalid client version.
7005 Invalid session guid format.
7006 Invalid folder id.
7007 Invalid parent folder id.
7008 Invalid folder name.
7009 Invalid file id.
7010 Favorites already contain this folder.
7011 Favorites do not contain this folder.
7012 Favorites already contain this file.
7013 Favorites do not contain this file.
7014 Invalid system log operation type.
7015 Invalid mobile receiver application name.
7016 Invalid ticket subject.
7017 Invalid Thru date format.
7018 Collection contains invalid id.
7019 Invalid secure message id.
7020 End date of range is earlier than start date.
7021 Invalid email format.
7022 To recipient should be provided.
7023 Distribution cannot include requested folder:
access denied.
7024 Distribution cannot include requested file:
access denied.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 74
7025 Invalid filter options value.
7026 Currently operation is not supported.
7027 File is quarantined.
7028 Cc invalid email format.
7029 Bcc invalid email format.
7030 Invalid secure message subject.
7031 Expired date does not satisfy server policy.
7032 Invalid secure message priority.
7033 Distribution cannot include requested folder:
folder does not exist.
7034 Distribution cannot include requested file:
file does not exist.
7035 Distribution cannot include requested file:
file is quarantined.
7036 Distribution does not contain attached folder.
7037 Distribution does not contain attached file.
7038 Distribution does not contain recipient [Recipient email]
7039 Distribution does not contain attached folders.
7040 Distribution does not contain attached files.
7041 Request login option does not correspond
to the server policy.
7042 Distribution cannot include requested folder:
folder is deleted.
7043 Distribution cannot include requested file:
file is deleted.
7044 Skip value must be greater or equal than 0.
7045 Invalid confirm password
7046 Message can only be discarded before it is sent.
7047 Message has been already sent.
7048 Access Denied, login from any mobile devices for this site is not allowed.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 75
7049 Access Denied, login from this mobile device for this user and application is not allowed.
102 Invalid Username or Password.
103 Requested folder does not exist.
104 File does not exist.
111 Distribution does not exist.
145 Missing new password.
146 Missing old password.
147 Invalid old password.
6 Invalid IP Address.
Thru REST API 1.0 / Reference 1.7 © 2014 Thru, Inc. All rights reserved | Page 76
About Trademarks and Abbreviations
Thru and the Thru logo are registered trademarks of Thru, Inc.
Microsoft, Windows, and Outlook are trademarks of Microsoft Corporation in the United States and/or other countries.
Other company or product names used in this manual and not included in the list above are trademarks of those companies and may be registered in certain jurisdictions.
© 2014 Thru, LLC All rights reserved.
909 Lake Carolyn Parkway, Suite 750 Irving, Texas 75039 Phone: 214.496.0100 Fax: 972.767.4523 www.thruinc.com