Files Management
Using Trillo Workbench APIs, manage folders and files from your application. Trillo provides user and group access control for files and folders. All files/folder operations are available as APIs.
The following diagram shows how you can use APIs from your program to manage folders and files. The files are stored in the Google Cloud Storage bucket. Trillo implements folder and folder access control by users and groups. Trillo provides APIs for copying, moving, removing (soft and permanent), accessing old versions, etc. Trilo provides API to obtain a signed URL for uploading and downloading files. A signed URL permits to upload and download files without having to go through the Trillo Workbench thus avoiding extra load on the service.
Folder and FIle Management using Trillo WOrkbench
Trillo File Manager is a standalone product. It is also a part of the Trillo Workbench. It is similar to DropBox or GDrive on the top of the Google Cloud Storage bucket. It has the following features:
- UI for folder and file management.
- Create folder hierarchy.
- Upload one or more files.
- Move, copy, delete, rename files.
- Versioning of files.
- Sharing of files.
- Download one or more files.
- SFTP server (including using public/private key-pairs).
- API for uploading and downloading files from an external client.
See the document Trillo File Manager Documentation for SFTP and user management. Its UI is intuitive.
This document discusses the file upload, download APIs for Trillo File Manager (or you can also refer to them as APIs of Trillo Workbench since it is integrated within it).
This section describes the concepts of the flow. The following section describes each API in detail.
Trillo uses the GCP Cloud storage bucket for files. But you don't have to worry about GCP configuration, managing its service tokens securely, etc. It is transparently taken care of by the Trillo platform. Instead, you use Trillo restful APIs. Trillo platform handles multiple environments, tenants, users, groups, folders. keeping the bucket content in sync with the database, etc.
Step 1 is to acquire an API access-token (like any other restful API). You may already have acquired access-token previously such as during login.
The following steps vary depending on the upload or download.
Step 2 call API to retrieve the signed URL for putting the file. The signed URL is used to transfer the file to the GCP bucket directly. The signed URL is hard to guess URL with encrypted security info in the parameter. It is also short-lived and becomes invalid after some time.
Step 3 use the signed URL to upload the file through Multipart/form-data request.
Step 4 save the file object into the database (Trillo platform maintains the cache of content on the file into the database for performance and implementing access control). Trillo platform will eventually, sync the bucket with the database. But the save call ensures that the database is in sync with the content of the bucket.
Step 2 call API to retrieve the signed URL for getting the file.
Step 3 use the signed URL to download the file. For example, you can open the URL in a new or the same browser table using JavaScript call.
Use the following API to get the authentication token. You would normally obtain it during the login if you are using the Trillo platform login. Otherwise, you can obtain it using a service account. Trillo provides an extension (since it is outside OAuth2 flow) to provide an access token on the behalf of the service account that acts on behalf of the user (this assumes that the proxy user is created inside the Trillo platform).
All restful API calls assume the following header. If no other headers are required, the headers section is skipped.
'Content-Type':'application/json'
End-point:
POST /oauth/token
Body:
Response:
{
"access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",
"token_type":"bearer",
"expires_in":3600,
"refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",
"scope": "comman separated list of roles"
}
Unless specified, all APIs need to be passed access-token in the header as follows:
'Authorization':'Bearer + <value of the accss token'
'Content-Type':'application/json'
Note space after Bearer.
The following sections describe 3 API calls for the upload flow.
The first step of the upload flow is to retrieve a signed URL.
End-point:
POST /foldersvc/cloudstorage/folder/retieveSignedUrl
Body:
{
“folderName” : <cloud storage bucket folder>,
"subFolder": "<sub folder if any>",
“contentType” :<file content type>,
“fileName” : “<name of the file to be uploaded>,
“method” : “PUT”
}
The parameter “method” : “PUT” above is a parameter to the signed URL.
It does not imply HTTP method.
The "subFolder" parameter is useful when loading a directory recursive.
You can also add it to the "folderName".
Response:
{
“code” : 200,
“data: {
“signedUrl” : “value of signed url”
}
}
The next step is to upload the actual file using the signed URL. The AJAX call is shown in the code snippet below.
End-point:
PUT <signed url value>
Header:
'Content-Type': 'multipart/formdata; charset=UTF-8'
Note this API uses a different content type.
Body:
{
actual file
}
Response:
Returns HTTP code 200 if successful. No body is returned.
The last step of the upload flow is to save the file object in the database.
End-point:
POST /foldersvc/cloudstorage/folder/retieveSignedUrl
Body:
{
“folderName” : <cloud storage bucket folder>,
"subFolder": "<sub folder if any>",
“contentType” :<file content type>,
“fileName” : “<name of the file to be uploaded>,
"provider":"cloudstorage"
}
Response: It returns the file object created in the database as JSON. An example is shown below.
{
"fileName":"TrillWorkbench-Database-Tabs.png",
"folderName":"/users/test201/Home/tmp",
"folderId":84,
"className":"",
"url":"#cloudstorage",
"contentUrl":"#cloudstorage",
"title":"TrillWorkbench-Database-Tabs.png",
"provider":"cloudstorage",
"size":79336,
"contentType":"image/png",
"_uniqueness_condition_":null,
"fileType":"png",
"idOfUser":3,
"userId":"test201",
"firstName":"Test",
"lastName":"Test123",
"topFolderId":82,
"createdAt":1615795228850,
"deletedAt":0,
"deleted":false,
"updatedAt":1615795228850,
"versionsCount":0,
"id":444
}
The following sections describe the steps of download flow.
The first step of the upload flow is to retrieve a signed URL.
End-point:
POST /foldersvc/cloudstorage/folder/retieveSignedUrl
Body:
{
“folderName” : <cloud storage bucket folder>,
“contentType” :<file content type>,
“fileName” : “<name of the file to be downloaded>,
"fileId" : "<databse id of the file>",
“method” : “GET”
}
The parameter “method” : “GET” above is a parameter to the signed URL.
It does not imply HTTP method.
In the above API you can pass, either "fileId", or "fileName"
and "folderName". If "fileId" is passed the the name of the file
and folder are retrieved from the database.
Response:
{
“code” : 200,
“data: {
“signedUrl” : “value of signed url”
}
}
Last modified 1yr ago