Get started with Storage API

Introduction

This quick start is going to help you work with using Storage API. Tutorial describes main operations required to create files with folders, retrieving and managing them.

Info

Skill level:

Basic

Duration:

45 minutes

Prerequisites

This tutorial assumes that you already have:

  • A tool such as Postman that can be used to execute http calls. These calls can also be made using the Try It button in the API documentation except from requests for file uploads.
  • Project iTwin created and configured. Try iTwins API.

1. Preparing to use Storage API

There are some actions, which should be completed before starting using Storage API.

1.1 Register an Application

You will need to register an application to use the iTwin Platform APIs. You can use the Register button to automatically create your first single page application (SPA). This will allow you to configure Authorization Code Flow for your SPA application and get the correct access token.

Once generated, you will be shown a few lines of code under the button.

  • IMJS_AUTH_CLIENT_CLIENT_ID - this is the unique identifier for your application. Displayed on application details page as Client ID.
  • IMJS_AUTH_CLIENT_REDIRECT_URI - specifies where users are redirected after they have chosen to authenticate your app. Displayed on application details page as one of Redirect URIs.
  • IMJS_AUTH_CLIENT_LOGOUT_URI - specifies where users can be returned to after logging out. Displayed on application details page as one of Post logout redirect URIs.
  • IMJS_AUTH_CLIENT_SCOPES - list of accesses granted to the application. Displayed on application details page as Scopes.

Or optionally: Register and configure your application manually following instructions in Register and modify an Application tutorial.

Requires you to sign in. Will automatically generate a Single page application (SPA) that is required to complete this tutorial. You will be able to manage your SPA from your My apps page.

1.2 Get a token

To make request to API user token is needed. There are several ways to get it.

Implement Authorization Code Flow in the application

Follow this article to implement Authorization code workflow in your application.

Here you can use Client ID generated from previous registration step.

Grab a user token from API reference "Try it" Section

  1. Go to Get top level folders and files by itwin - Storage
  2. Click "Try it" button.
  3. On Authorization section select "AuthorizationCode".
  4. After popup closes Authorization header with your user token value should be visible.
  5. Save user token value for this tutorial.

Use user token to replace JWT_TOKEN dynamic parameter in the next steps.

1.3 Get a link to the Storage

Files and folders created via Storage API are associated with iTwin. If iTwin is already existing then root folder, which is parent folder to first level files and folders could be retrieved by getting iTwins operation.

Another way of getting link to the storage is by executing HTTP GET https://api.bentley.com/storage?iTwinId=ITWIN_ID request.

You can execute the request in Get top level folders and files by itwin documentation page, “Try it” section.

The Root Folder serves as the primary directory for your iTwin, identified by the iTwinId.

Root Folder: Base folder created when iTwin is created.

Top level folders with files should be returned if there are any. Response will contain link to the storage, to the root folder.

HTTP request


http
GET https://api.bentley.com/storage?iTwinId=ITWIN_ID HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Body


json
{
"items": [],
"_links": {
  "self": {
      "href": "https://api.bentley.com/storage?iTwinId=ITWIN_ID&$skip=0&$top=100"
  },
  "prev": {
      "href": "https://api.bentley.com/storage?iTwinId=ITWIN_ID&$skip=0&$top=100"
  },
  "next": {
      "href": "https://api.bentley.com/storage?iTwinId=ITWIN_ID&$skip=100&$top=100"
  },
  "folder": {
      "href": "https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s"
  }
}
}

2. Get folder

To retrieve root folder, HTTP GET https://api.bentley.com/storage/folders/FOLDER_ID request should be executed by using link from previous section or by existing another root folder ID.

Here, folderId is required in the parameters. This folderId is the Id of the folder in which you want to retrieve.

You can execute the request in Get folder documentation page, “Try it” section.

HTTP request


http
GET https://api.bentley.com/storage/folders/FOLDER_ID HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Body


json
{
"folder": {
  "id": "FOLDER_ID",
  "displayName": "test",
  "description": "test folder",
  "path": "folderName/test",
  "lastModifiedByDisplayName": "Bob User",
  "createdDateTime": "2020-05-03T11:05:11.0133549Z",
  "lastModifiedDateTime": "2020-05-03T11:05:11.0133549Z",
  "parentFolderId": "TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s",
  "_links": {
    "createdBy": {
        "href": "https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
    },
    "lastModifiedBy": {
        "href": "https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
    },
    "parentFolder": {
        "href": "https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s"
    }
  }
}
}

3. Create folder

Files are organized in a folder structure. To create folder request, send the payload using HTTP POST https://api.bentley.com/storage/folders/FOLDER_ID/folders. displayName is required, while description is optional in the payload.

Here, folderId is required in the parameters. This folderId is the Id of the folder in which you want to create a folder.

You can execute the request in Create folder documentation page, “Try it” section.

Folder should be created and ready to be used.

HTTP request


http
POST https://api.bentley.com/storage/folders/FOLDER_ID/folders HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Request Body


json
{
"displayName": "test",
"description": "test folder"
}

Response Body


json
{
"folder": {
  "id": "TYJsPN0xtkWId0yUrXkS5pN5AQzuullIkxz5aDnDJSI",
  "displayName": "test",
  "description": "test folder",
  "path": "test",
  "lastModifiedByDisplayName": "Bob User",
  "createdDateTime": "2020-05-03T11:05:11.0133549Z",
  "lastModifiedDateTime": "2020-05-03T11:05:11.0133549Z",
  "parentFolderId": "TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s",
  "_links": {
    "createdBy": {
        "href": "https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
    },
    "lastModifiedBy": {
        "href": "https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
    },
    "parentFolder": {
        "href": "https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s"
    }
  }
}
}

Response headers


http
Location: https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5pN5AQzuullIkxz5aDnDJSI

4. Create file

Create file is a three step process. First, create the metadata, then the actual file should be uploaded, and finally confirmation request needs to be sent. Created files can be synchronized with iModels. Try Synchronization API.

4.1 Create file's metadata

Use root folder ID from previous step to create a file in the same directory as previously created folder and execute HTTP POST https://api.bentley.com/storage/folders/FOLDER_ID/files request. displayName is required, while description is optional in the payload.

You can execute the request in Create file documentation page, “Try it” section.

Here, folderId is required in the parameters. This folderId is the Id of the folder in which you want to create a file.

File's metadata should be created and links from the response will be used in the further steps to create file.

HTTP request


http
POST https://api.bentley.com/storage/folders/FOLDER_ID/files HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Request Body


json
{
"displayName": "test.txt",
"description": "test file"
}

Response Body


json
{
"_links": {
  "completeUrl": {
      "href": "https://api.bentley.com/storage/files/TYJsPN0xtkWId0yUrXkS5s4FlCroosBMlyDhZZmlzoc/complete"
  },
  "uploadUrl": {
      "href": "https://projectshareprodeussa01.blob.core.windows.net/azuresqldbecpluginstorage/ProjectShare/File/b6145b7f-fee9-4a13-b1e4-5d061970373e?sv=2017-04-17&sr=b&sig=4NfdEriAONQhbHGkrTAL4bNMzjW8Qm5l%2FoEPiSQl%2BPo%3D&se=2020-10-19T15:12:51Z&sp=rw&rscd=attachment%3B%20filename%3D%22test.txt%22&userid=b905387c-a685-4d27-aab7-468c9ff0c9a6"
  }
}
}

4.2 Upload actual file

To upload actual file, use a request. A tool such as Postman should be used to make http request. Url should be picked from previous request's response where uploadUrl is specified. The maximum file size to upload with single request is 256 MiB. If bigger file needs to be uploaded there are ways to use Azure libraries to upload file via given Azure SAS url or by uploading file with multiple requests.

For large size file upload you can upload the file in chunks using FileStream depending on the tech-stack.

Note: Authorization header is not required for this request.

HTTP request


http
PUT https://projectshareprodeussa01.blob.core.windows.net/azuresqldbecpluginstorage/ProjectShare/File/b6145b7f-fee9-4a13-b1e4-5d061970373e?sv=2017-04-17&sr=b&sig=4NfdEriAONQhbHGkrTAL4bNMzjW8Qm5l%2FoEPiSQl%2BPo%3D&se=2020-10-19T15:12:51Z&sp=rw&rscd=attachment%3B%20filename%3D%22test.txt%22&userid=b905387c-a685-4d27-aab7-468c9ff0c9a6 HTTP/1.1
x-ms-blob-type: BlockBlob

Request Body


json
test

4.3 Complete file creation

Confirmation is required after file upload. That will make file visible, and it could be used further. Url should be picked from the first step of file's metadata creation where completeUrl is specified.

Execute the request in Complete file upload page, “Try it” section.

Note: If you add or change request body format, you will reset your changes to body content. So, Do not add anything in body.

Your file should be placed in the storage and be ready to be used.

HTTP request


http
POST https://api.bentley.com/storage/files/TYJsPN0xtkWId0yUrXkS5s4FlCroosBMlyDhZZmlzoc/complete HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Body


json
{
"file":{
  "id":"TYJsPN0xtkWId0yUrXkS5s4FlCroosBMlyDhZZmlzoc",
  "displayName":"test.txt",
  "description":"test file",
  "path":"folderName/test.txt",
  "size":8,
  "lastModifiedByDisplayName":"Bob User",
  "createdDateTime":"2020-05-03T11:05:11.0133549Z",
  "lastModifiedDateTime":"2020-05-03T11:05:11.0133549Z",
  "parentFolderId":"TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s",
  "_links":{
    "createdBy":{
      "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
    },
    "lastModifiedBy":{
      "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
    },
    "parentFolder":{
      "href":"https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s"
    }
  }
}
}

5. Download file

Download the files by executing HTTP GET https://api.bentley.com/storage/files/FILE_ID/download request.

The request can be executed in the Complete file upload page, “Try it” section.

Download the file with the content specified in the previous request.

Execute a follow-up request using the link in the Location header, this should return a 302 redirect response.

HTTP request


http
GET https://api.bentley.com/storage/files/FILE_ID/download HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+octet-stream
Authorization: Bearer JWT_TOKEN

Response Headers


http
Location: https://projectshareprodeussa01.blob.core.windows.net/azuresqldbecpluginstorage/ProjectShare/File/b6145b7f-fee9-4a13-b1e4-5d061970373e?sv=2017-04-17&sr=b&sig=4NfdEriAONQhbHGkrTAL4bNMzjW8Qm5l%2FoEPiSQl%2BPo%3D&se=2020-10-19T15:12:51Z&sp=rw&rscd=attachment%3B%20filename%3D%22test.txt%22&userid=b905387c-a685-4d27-aab7-468c9ff0c9a6

6. Get folders and files in the folder

Usually for navigating through folders and files request execute HTTP GET https://api.bentley.com/storage/folders/FOLDER_ID/list with root folder id as folder id should be used to retrieve the items of root folder. It is possible to set page size by specifying $skip and $top query parameters. $top default is set to 100 if it is not changed.

You can execute the request in Get folders and files in folder documentation page, “Try it” section.

Here, folderId is required in the parameters. This folderId is the Id of the folder from which you want files and folders.

Your created folder and file should be retrieved.

HTTP request


http
GET https://api.bentley.com/storage/folders/FOLDER_ID/list HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Body


json
{
"items":[
  {
    "type":"folder",
    "id":"TYJsPN0xtkWId0yUrXkS5pN5AQzuullIkxz5aDnDJSI",
    "displayName":"test",
    "description":"test folder",
    "path":"test",
    "lastModifiedByDisplayName":"Bob User",
    "createdDateTime":"2020-05-03T11:05:11.0133549Z",
    "lastModifiedDateTime":"2020-05-03T11:05:11.0133549Z",
    "parentFolderId":"TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s",
    "_links":{
      "createdBy":{
        "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
      },
      "lastModifiedBy":{
        "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
      },
      "parentFolder":{
        "href":"https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s"
      }
    }
  },
  {
    "type":"file",
    "id":"TYJsPN0xtkWId0yUrXkS5s4FlCroosBMlyDhZZmlzoc",
    "displayName":"test.txt",
    "description":"test file",
    "path":"folderName/test.txt",
    "size":8,
    "lastModifiedByDisplayName":"Bob User",
    "createdDateTime":"2020-05-03T11:05:11.0133549Z",
    "lastModifiedDateTime":"2020-05-03T11:05:11.0133549Z",
    "parentFolderId":"TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s",
    "_links":{
      "createdBy":{
        "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
      },
      "lastModifiedBy":{
        "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
      },
      "parentFolder":{
        "href":"https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s"
      }
    }
  }
],
"_links":{
  "self":{
    "href":"https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s/list?$skip=0&$top=100"
  },
  "prev":{
    "href":"https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s/list?$skip=0&$top=100"
  },
  "next":{
    "href":"https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s/list?$skip=100&$top=100"
  }
}
}

7. Update folder

To update folder's metadata, request with payload should be send to HTTP PATCH https://api.bentley.com/storage/files/FOLDER_ID. Metadata including displayName and description properties can be updated by sending this request.

You can execute the request in Update folder documentation page, “Try it” section.

Here, folderId is required in the parameters. This folderId is the Id of the folder from which you want files and folders.

Folder's properties should be updated.

HTTP request


http
PATCH https://api.bentley.com/storage/folders/FOLDER_ID HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Request Body


json
{
"displayName":"test update",
"description":"test folder update"
}

Response Body


json
{
"folder":{
  "id":"TYJsPN0xtkWId0yUrXkS5pN5AQzuullIkxz5aDnDJSI",
  "displayName":"test",
  "description":"test folder",
  "path":"test",
  "lastModifiedByDisplayName":"Bob User",
  "createdDateTime":"2020-05-03T11:05:11.0133549Z",
  "lastModifiedDateTime":"2020-05-03T11:09:02.0954397Z",
  "parentFolderId":"TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s",
  "_links":{
    "createdBy":{
      "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
    },
    "lastModifiedBy":{
      "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
    },
    "parentFolder":{
      "href":"https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s"
    }
  }
}
}

8. Update file

To update file's metadata, request with payload should be send to HTTP PATCH https://api.bentley.com/storage/files/FILE_ID. File metadata of displayName and description properties can be updated by sending this request same as with folder update. displayName is required in the payload.

You can execute the request in Update file documentation page, “Try it” section.

Here, fileId is required in the parameters. This fileId is the Id of the file which you want to update.

File's properties should be updated.

HTTP request


http
PATCH https://api.bentley.com/storage/files/FILE_ID HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Request Body


json
{
"displayName":"test update.txt",
"description":"test file update"
}

Response Body


json
{
"folder":{
  "id":"TYJsPN0xtkWId0yUrXkS5pN5AQzuullIkxz5aDnDJSI",
  "displayName":"test",
  "description":"test folder",
  "path":"test",
  "lastModifiedByDisplayName":"Bob User",
  "createdDateTime":"2020-05-03T11:05:11.0133549Z",
  "lastModifiedDateTime":"2020-05-03T11:15:02.0954397Z",
  "parentFolderId":"TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s",
  "_links":{
    "createdBy":{
      "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
    },
    "lastModifiedBy":{
      "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
    },
    "parentFolder":{
      "href":"https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s"
    }
  }
}
}

9. Update file's content

Update file's content is a three step process. Request for initiating update need to be made first then actual file should be uploaded and finally confirmation request needs to be sent. Which is complete File Upload Link.

You can execute the request in Update file documentation page, “Try it” section.

9.1 Initiate file's content update

Use file ID from previous step and execute HTTP POST https://api.bentley.com/storage/files/FILE_ID/updatecontent request.

You can execute the request in Update file's content documentation page, “Try it” section.

Hyperlinks will be created, which should be used be used in the further steps to update file's content.

HTTP request


http
POST https://api.bentley.com/storage/files/FILE_ID/updatecontent HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Body


json
{
"_links":{
  "completeUrl":{
    "href":"https://api.bentley.com/storage/files/TYJsPN0xtkWId0yUrXkS5s4FlCroosBMlyDhZZmlzoc/complete"
  },
  "uploadUrl":{
    "href":"https://projectshareprodeussa01.blob.core.windows.net/azuresqldbecpluginstorage/ProjectShare/File/b6145b7f-fee9-4a13-b1e4-5d061970373e?sv=2017-04-17&sr=b&sig=4NfdEriAONQhbHGkrTAL4bNMzjW8Qm5l%2FoEPiSQl%2BPo%3D&se=2020-10-19T15:12:51Z&sp=rw&rscd=attachment%3B%20filename%3D%22test.txt%22&userid=b905387c-a685-4d27-aab7-468c9ff0c9a6"
  }
}
}

9.2 Upload actual file

This request is used to upload actual file. A tool such as Postman should be used to make http request. Url should be picked from previous request's response where uploadUrl is specified. The maximum size of the file is 256 MiB. If bigger file needs to be uploaded there are possibility to use Azure libraries to upload file via given Azure SAS url or by uploading file with multiple requests.

For large size file upload you can upload the file in chunks using FileStream depending on the tech-stack.

Note: Authorization headers is not required for this request.

HTTP request


http
PUT https://projectshareprodeussa01.blob.core.windows.net/azuresqldbecpluginstorage/ProjectShare/File/b6145b7f-fee9-4a13-b1e4-5d061970373e?sv=2017-04-17&sr=b&sig=4NfdEriAONQhbHGkrTAL4bNMzjW8Qm5l%2FoEPiSQl%2BPo%3D&se=2020-10-19T15:12:51Z&sp=rw&rscd=attachment%3B%20filename%3D%22test.txt%22&userid=b905387c-a685-4d27-aab7-468c9ff0c9a6 HTTP/1.1
x-ms-blob-type: BlockBlob

Request Body


json
test update

9.3 Complete file's content upload

After uploading actual file confirmation is needed. Url should be picked from the first step where completeUrl is specified.

You can execute the request in Complete file upload page, “Try it” section.

File's content should be updated.

If you add or change request body format, you will reset your changes to body content. So, Do not add anything in body.

HTTP request


http
POST https://api.bentley.com/storage/files/TYJsPN0xtkWId0yUrXkS5s4FlCroosBMlyDhZZmlzoc/complete HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Body


json
{
"file":{
  "id":"TYJsPN0xtkWId0yUrXkS5s4FlCroosBMlyDhZZmlzoc",
  "displayName":"test.txt",
  "description":"test file",
  "path":"folderName/test.txt",
  "size":8,
  "lastModifiedByDisplayName":"Bob User",
  "createdDateTime":"2020-05-03T11:05:11.0133549Z",
  "lastModifiedDateTime":"2020-05-03T11:25:46.8659753Z",
  "parentFolderId":"TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s",
  "_links":{
    "createdBy":{
      "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
    },
    "lastModifiedBy":{
      "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
    },
    "parentFolder":{
      "href":"https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s"
    }
  }
}
}

10. Recycle bin operations

Files and folders can be deleted and restored. Deleted items can be queried as well because they will be only soft deleted and kept in the recycle bin. Items from recycle bin can be deleted manually if there is no reason to keep them longer otherwise they will be removed automatically after 30 days.

10.1 Delete folder

Let's delete created folder. Execute HTTP DELETE https://api.bentley.com/storage/folders/FOLDER_ID request.

You can execute the request in Delete folder page, “Try it” section.

Here, folderId is required in the parameters. This folderId is the Id of the folder which you want to update.

Folder should be soft deleted. Folder will be added to recycle bin and it would be deleted automatically after 30 days.

HTTP request


http
DELETE https://api.bentley.com/storage/folders/FOLDER_ID HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

10.2 Delete file

Let's delete created file as well. Execute HTTP DELETE https://api.bentley.com/storage/files/FILE_ID request.

You can execute the request in Delete file page, “Try it” section.

Here, fileId is required in the parameters. This fileId is the Id of the file which you want to delete.

File should be soft deleted. File will be added to recycle bin and it would be deleted automatically after 30 days.

HTTP request


http
DELETE https://api.bentley.com/storage/files/FILE_ID HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

10.3. Get folders and files in recycle bin

To retrieve soft-deleted files and folder, send HTTP GET https://api.bentley.com/recycleBin?iTwinId=ITWIN_ID. It is possible to set page size by specifying $skip and $top query parameters. $top default is set to 100 if it is not changed.

You can execute the request in Get folders and files in recycle bin documentation page, “Try it” section.

Here, iTwinId is required in the parameters. This iTwinId is the Id of the iTwin.

The previously deleted files and folders are displayed.

HTTP request


http
GET https://api.bentley.com/storage/recycleBin?iTwinId=ITWIN_ID HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

Response Body


json
{
"items":[
  {
    "type":"folder",
    "id":"TYJsPN0xtkWId0yUrXkS5pN5AQzuullIkxz5aDnDJSI",
    "displayName":"test",
    "description":"test folder",
    "path":"test",
    "lastModifiedByDisplayName":"Bob User",
    "createdDateTime":"2020-05-03T11:05:11.0133549Z",
    "lastModifiedDateTime":"2020-05-03T11:05:11.0133549Z",
    "parentFolderId":"TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s",
    "_links":{
      "createdBy":{
        "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
      },
      "lastModifiedBy":{
        "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
      },
      "parentFolder":{
        "href":"https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s"
      }
    }
  },
  {
    "type":"file",
    "id":"TYJsPN0xtkWId0yUrXkS5s4FlCroosBMlyDhZZmlzoc",
    "displayName":"test.txt",
    "description":"test file",
    "path":"folderName/test.txt",
    "size":8,
    "lastModifiedByDisplayName":"Bob User",
    "createdDateTime":"2020-05-03T11:05:11.0133549Z",
    "lastModifiedDateTime":"2020-05-03T11:25:46.8659753Z",
    "parentFolderId":"TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s",
    "_links":{
      "createdBy":{
        "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
      },
      "lastModifiedBy":{
        "href":"https://api.bentley.com/projects/6959daff-27f5-4b87-96ea-9917daa3a8ff/members/1140f95b-1ba0-49d9-bbf4-b53e54d80387"
      },
      "parentFolder":{
        "href":"https://api.bentley.com/storage/folders/TYJsPN0xtkWId0yUrXkS5g0CIYaGZLxEozrWBCOcS_s"
      }
    }
  }
],
"_links":{
  "self":{
    "href":"https://api.bentley.com/storage/recycleBin?iTwinId=ITWIN_ID&$skip=0&$top=100"
  },
  "prev":{
    "href":"https://api.bentley.com/storage/recycleBin?iTwinId=ITWIN_ID&$skip=0&$top=100"
  },
  "next":{
    "href":"https://api.bentley.com/storage/recycleBin?iTwinId=ITWIN_ID&$skip=100&$top=100"
  }
}
}

10.4 Restore folder

It is time to restore deleted folder. Execute HTTP POST https://api.bentley.com/storage/recycleBin/folders/FOLDER_ID/restore request.

You can execute the request in Restore folder page, “Try it” section.

Here, folderId is required in the parameters. This folderId is the Id of the folder which you want to restore.

Folder should be successfully restored. File can be restored with in the 30 Days

HTTP request


http
POST https://api.bentley.com/storage/recycleBin/folders/FOLDER_ID/restore HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN

10.5 Restore file

To restore a file, execute HTTP POST https://api.bentley.com/storage/recycleBin/files/FILE_ID/restore request.

You can execute the request in Restore file page, “Try it” section.

Here, fileId is required in the parameters. This fileId is the Id of the file which you want to restore.

File should be successfully restored.

HTTP request


http
POST https://api.bentley.com/storage/recycleBin/files/FILE_ID/restore HTTP/1.1
Accept: application/vnd.bentley.itwin-platform.v1+json
Authorization: Bearer JWT_TOKEN