Introduction
This tutorial will take you through the process of uploading a component to a catalog in an organization.
By the end of this walk-through, you will be able to utilize the API endpoints in order to upload components to a catalog and associate additional documents to the uploaded component.
Info
Skill level:
Basic
Duration:
20 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 theTryIt
button in the API documentation. - User must be affiliated with an Organization and should either be an Organization Administrator or have 'Upload' and 'Read' permission at Organization level to upload components to catalog.
- For more information about User Management please visit our Bentley Communities Licensing, Cloud, and Web Services wiki page.
- A design file is required to upload a component. Design file is a CAD file, used in CAD applications i.e. MicroStation, Revit etc. Library API supports three types of files to upload a component i.e. rfa, dgn and cel.
- In this example we will upload a component from rfa file, though dgn and cell files can also be used to upload the component with same steps. You should have one of these files to upload a component.
Postman
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 whether or not 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.
Register a basic SPA App for this 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.
2. Get a token
Before you can make a request to the APIs, a 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.
Grab a user token from Api reference "Try it" Section
- Go here
- Click
Try it
button. - Under the
Authorization
section, selectauthorizationCode
from the dropdown. - After the sign in popup closes, the
Authorization
header with token value should be visible beneath theHTTP request
dropdown. - Copy & paste the
Authorization
value for this tutorial.
3. Create a new Catalog
The Library API is used to create and manage catalogs. A POST call to the https://api.bentley.com/library/catalogs
endpoint will create a new catalog. Only displayName
is required for creating a new catalog. It must be unique
so if you get a Conflict error then you will need to replace displayName with unique value. See the Library API documentation for descriptions of the different properties.
The POST call will return a new catalog instance. The id
can be used to upload component to the catalog. The catalog Id is also used in other Library API endpoints. You may want to save this Id to use in other endpoints.
In case you already have id
of an existing catalog, it can be used to upload the component, instead of creating a new catalog.
Request Syntax
POST https://api.bentley.com/library/catalogs HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN
Request Body
{
"displayName": "Tutorial Sample Catalog",
"description": "Tutorial Sample Description",
"region": "US",
"hashtags": ["SampleHashtag1", "SampleHashtag2"]
}
Response Headers
HTTP/1.1 201 Created
content-length: 937
content-type: application/json
date: Thu, 24 Jun 2021 14:44:18 GMT
request-context: appId=cid-v1:7a353d36-9a8b-423e-965e-9d7f51324584
x-correlation-id: 5262b13f-394e-49b8-95ea-a5361d2513a3
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US
Response Body
{
"catalog": {
"id": "7f427c30-8dce-4803-81dc-e8681a3bd757",
"displayName": "Tutorial Sample Catalog",
"description": "Tutorial Sample Description",
"region": "US",
"createdDateTime": "2021-09-06T06:03:56.1923267Z",
"lastModifiedDateTime": "2021-09-06T06:03:56.1923267Z",
"hashtags": ["SampleHashtag1", "SampleHashtag2"]
}
}
4. Referenced Entities
A component can have referenced entities i.e. Category, Application and Manufacturer. These are optional properties of a component to be uploaded, in case this information is not provided with request body, upload process will try extract the same from the design file, provided design file contains this information.
The Library API provides endpoints to create and manage these referenced entities. For this example, we will not use referenced entities in the upload and instead make use of information provided in the design file.
You can use following TryIt options in the Library API documentation to create these entities.
Library API documentation to create Category
5. Upload Component
A component can be uploaded using rfa, dgn or cel file. In this example we will use rfa file to upload component to the catalog. Upload component is a multi-step process. Make an upload request with upload request body, then upload the design file and/or TypeCatalog file and after that you can optionally add any additional reference documents to the newly uploaded component. TypeCatalog files are only used optionally with rfa files, so this will not be required in case of dgn or cel files.
5.1 Make Upload Component Request
In the first step, create upload component request body and make a POST call to https://api.bentley.com/library/upload-component
endpoint. There is an option to make component a 'TypeCatalog' component by setting isTypeCatalog
property to true. A TypeCatalog Component expects to upload a text file (must have txt extension) as well along with the design file.
In this example we will use TypeCatalog component. Only fileName
and catalogIds
is required to upload a component to a catalog, in case catalogIds
not provided, component will be uploaded to user organization and won't belong to any catalog. Provide catalog Id (retrieved in previous steps) to catalogIds field,
this field expects a collection of catalogIds, in case a component should be uploaded to multiple catalogs, you can provide multiple catalog Ids in this field.
Upload is a long running activity and response contains location header value, this will be used to track the progress. You may want to save this header value, which will be used in next steps.
See the Library API documentation for descriptions of the different properties.
Request Syntax
POST https://api.bentley.com/library/upload-component HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN
Request Body
{
"fileName": "TutorialSampleFile.rfa",
"componentName": "Tutorial Sample Component",
"description": "Tutorial Sample Description",
"searchTags": [
"SampleTag1",
"SampleTag2"
],
"catalogs": [
"7f427c30-8dce-4803-81dc-e8681a3bd757"
],
"category": null,
"application": null,
"manufacturer": null,
"isTypeCatalog": true
}
Response Headers
HTTP/1.1 202 Accepted
content-length: 973
date: Mon, 06 Sep 2021 15:05:38 GMT
location: https://api.bentley.com/library/jobs/2517713600604274285_b4ac4d02-bc16-48a3-a468-b277ea74a7cb
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
x-correlation-id: 2d4f3784-74c9-4e8d-bf81-939a27b16f54
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US
Response Body
{
"uploadComponent": {
"fileName": "TutorialSampleFile.rfa",
"componentName": "Tutorial Sample Component",
"description": "Tutorial Sample Description",
"sessionId": "70f72644-ef2f-4673-a327-ff0140b448a8",
"searchTags": ["SampleTag1", "SampleTag2"],
"isTypeCatalog": true,
"_links": {
"catalogs": [{
"href": "https://api.bentley.com/library/catalogs/7f427c30-8dce-4803-81dc-e8681a3bd757"
}],
"typeCatalogUploadUrl": {
"href": "https://componentscenprodeussa01.blob.core.windows.net/private-temporary-type-catalog-files/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288.typecatalog?sv=2018-03-28&sr=b&sig=cpt24N23osjV3be6KmAHU2T%2FweVO0%2Fb%2FcRLFS3nQYW0%3D&se=2021-09-06T16%3A15%3A22Z&sp=rcw"
},
"designFileUploadUrl": {
"href": "https://componentscenprodeussa01.blob.core.windows.net/private-temporary-design-files/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288.design?sv=2018-03-28&sr=b&sig=xJGhNSl5Ti0VHvIdhcqqRws6d7zgxMyK05xAwgrSrx4%3D&se=2021-09-06T16%3A15%3A22Z&sp=rcw"
}
}
}
}
5.2 Upload Files
Response from upload request contains temporary urls to upload files under _links
property value. Please note in this case there are two urls. _links->designFileUploadUrl
to upload the design file and since this is a TypeCatalog Component, there is another url _links->typeCatalogUploadUrl
to upload TypeCatalog text file. In case isTypeCatalog
property is set to false in upload request, response will have only one file upload url _links->designFileUploadUrl
. TypeCatalog text file must be uploaded before uploading the design file.
File upload can be done by making a Http PUT request on the provided url via tool such as Postman
or programmatically use Azure libraries to upload file (https://docs.microsoft.com/en-us/rest/api/storageservices/put-blob).
Request Syntax
PUT https://componentscenprodeussa01.blob.core.windows.net/private-temporary-type-catalog-files/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288.typecatalog?sv=2018-03-28&sr=b&sig=cpt24N23osjV3be6KmAHU2T%2FweVO0%2Fb%2FcRLFS3nQYW0%3D&se=2021-09-06T16%3A15%3A22Z&sp=rcw HTTP/1.1
Request Headers
x-ms-blob-type: BlockBlob
Request Body
TypeCatalog File Binary Content
Request Syntax
PUT https://componentscenprodeussa01.blob.core.windows.net/private-temporary-design-files/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288.design?sv=2018-03-28&sr=b&sig=xJGhNSl5Ti0VHvIdhcqqRws6d7zgxMyK05xAwgrSrx4%3D&se=2021-09-06T16%3A15%3A22Z&sp=rcw HTTP/1.1
Request Headers
x-ms-blob-type: BlockBlob
Request Body
Design File Binary Content
5.2 Get Upload Job Status
Upload component is a long running activity and runs in background, It starts once design file upload is complete. Response of upload request contains location header containing jobs endpoint with current upload job id, this is used to track the status of the background upload activity.
Make a GET call to location header value (https://api.bentley.com/library/jobs/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288
) to get the upload job status. Once upload activity is successfully complete, response of jobs endpoint 'status' property value will be 'Success'.
At this point, upload component is complete and a new component has been created. Response also provides link to this newly created component under _links->component->href
property, which can be used to retrieve the component from repository.
Request Syntax
GET https://api.bentley.com/library/jobs/2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288 HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN
Response Headers
HTTP/1.1 200 OK
cache-control: no-cache
content-encoding: gzip
content-type: application/json
date: Mon, 06 Sep 2021 15:26:28 GMT
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
vary: Accept-Encoding
x-content-type-options: nosniff
x-correlation-id: 2aadd82c-527e-4761-80d7-c8fc8191242c
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US
x-ms-request-id: 2e67c236-b002-0069-7133-a37573000000
x-ms-version: 2017-04-17
Response Body
{
"job": {
"id": "2517713594778387339_a1e3bf29-de93-4fd5-933f-da02078b0288",
"displayName": "TutorialSampleFile.rfa",
"jobSize": 749568,
"progress": 0,
"status": "Success",
"type": "Upload",
"error": null,
"_links": {
"component": {
"href": "https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7"
}
}
}
}
5.3 Get Component
Property _links->component->href
from the jobs response in the previous step, provides endpoint for the component created during upload activity. Make GET call to this endpoint (https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7
) to retrieve the component.
Response contains the component, you can note under _links
property in the response, there is information/links about referenced entities of the component i.e. application, manufacturer and category. This is extracted from the design file during the upload activity. This information
can only be extracted if design file used in the upload process contains information about referenced entities.
Request Syntax
GET https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7 HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN
Response Headers
HTTP/1.1 200 OK
content-encoding: gzip
content-type: application/json
date: Mon, 06 Sep 2021 15:30:11 GMT
odata-version: 4.0
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
vary: Accept-Encoding
x-correlation-id: 007f78fc-200d-4b80-8f9d-3594e685a674
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US
Response Body
{
"component": {
"id": "57fefe11-df1d-40c7-ae1a-02e233b9a7c7",
"displayName": "Tutorial Sample Component",
"description": "Tutorial Sample Description",
"state": "Draft",
"createdDateTime": "2021-09-06T15:17:45.8834641Z",
"lastModifiedDateTime": "2021-09-06T15:17:46.4509552Z",
"supportedFileTypes": ["RFA"],
"hashtags": ["SampleTag1", "SampleTag2"],
"_links": {
"catalogs": [{
"href": "https://api.bentley.com/library/catalogs/7f427c30-8dce-4803-81dc-e8681a3bd757"
}],
"application": {
"href": "https://api.bentley.com/library/applications/1418693a-8f60-4719-af0b-ceee1ad41e33"
},
"manufacturer": {
"href": "https://api.bentley.com/library/manufacturers/d4485150-ad6d-4d76-a3e2-50a0f690afc9"
},
"category": {
"href": "https://api.bentley.com/library/categories/63b7d70a-a426-4530-8c0f-3efd6a6c0da7"
}
}
}
}
5.4 Modify Component
After the component is uploaded, next step can be to make changes in the component. A PUT call to https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7
endpoint updates the component. Let's change the 'state' property of the component. By default on upload, a component 'state' property is set to
'Draft'. This property can have enum values Draft, Published, Checked, Approved and Archived. Let's set the value to 'Published'. Also note Update Component request expects request body must contain all the desired properties since this will replace existing component with current component definition.
See the Library API documentation for descriptions of the different properties.
Request Syntax
PUT https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7 HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN
Request Body
{
"displayName": "Tutorial Sample Component",
"description": "Tutorial Sample Description",
"state": "Published",
"catalogs": [
"7f427c30-8dce-4803-81dc-e8681a3bd757"
],
"category": "63b7d70a-a426-4530-8c0f-3efd6a6c0da7",
"application": "1418693a-8f60-4719-af0b-ceee1ad41e33",
"manufacturer": "d4485150-ad6d-4d76-a3e2-50a0f690afc9",
"hashtags": ["SampleTag1", "SampleTag2"]
}
Response Headers
HTTP/1.1 200 OK
content-encoding: gzip
content-type: application/json
date: Fri, 06 Sep 2021 15:37:05 GMT
odata-version: 4.0
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
vary: Accept-Encoding
x-correlation-id: 95bf368d-0d16-4913-b4ce-05caf4653c30
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US
Response Body
{
"component": {
"id": "57fefe11-df1d-40c7-ae1a-02e233b9a7c7",
"displayName": "Tutorial Sample Component",
"description": "Tutorial Sample Description",
"state": "Published",
"createdDateTime": "2021-09-06T15:17:45.8834641Z",
"lastModifiedDateTime": "2021-09-06T15:37:06.1378844Z",
"supportedFileTypes": ["RFA"],
"hashtags": ["SampleTag1", "SampleTag2"],
"_links": {
"catalogs": [{
"href": "https://api.bentley.com/library/catalogs/7f427c30-8dce-4803-81dc-e8681a3bd757"
}],
"application": {
"href": "https://api.bentley.com/library/applications/1418693a-8f60-4719-af0b-ceee1ad41e33"
},
"manufacturer": {
"href": "https://api.bentley.com/library/manufacturers/d4485150-ad6d-4d76-a3e2-50a0f690afc9"
},
"category": {
"href": "https://api.bentley.com/library/categories/63b7d70a-a426-4530-8c0f-3efd6a6c0da7"
}
}
}
}
6 Add Documents
Upload Component activity associate few documents to the component during the process. Design file and TypeCatalog file uploaded in previous steps are associated to the component as component design and typeCatalog documents respectively. Upload process also gets thumbnail image from the design file and associates it as thumbnail document. You can also associate additional documents after component is created. You can associate reference documents, images or even additional design files to the component. In this example we will associate a reference document to the component, other documents can also be associated with same steps, the only difference is setting the value of 'purpose' property in document request body.
See the Library API documentation for descriptions of the different properties.
Adding document is a multi-step process, we will go through these steps next.
6.1 Create Document Instance
A POST call to https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents
endpoint will create a new document instance for the component. displayName
, purpose
and extension
are required properties. purpose
can have enum values Design, Thumbnail, Reference, GalleryImage and TypeCatalog, depending upon which type of document you want to associate to a component. As we are associating a reference document, purpose
should be set to 'Reference'.
The POST call will return a new document instance. The id
will be used in next steps, you may want to save this Id. At this moment a document instance has been associated
to the component but there is no actual file attached to this document. We will do that in the next step.
Request Syntax
POST https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN
Request Body
{
"displayName": "Tutorial Sample Document",
"extension": "pdf",
"purpose": "Reference",
"available": false,
"isActive": true,
"version": null,
"previousVersionId": null,
"associatedDesignDocument": null
}
Response Headers
HTTP/1.1 201 Created
content-length: 704
content-type: application/json
date: Mon, 06 Sep 2021 15:46:51 GMT
location: https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/bf15e508-3b59-49d5-a1b5-ea9ef9d66515
odata-version: 4.0
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
x-correlation-id: 63ca0126-3234-4bf4-846c-27c7e8e16458
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US
Response Body
{
"document": {
"id": "bf15e508-3b59-49d5-a1b5-ea9ef9d66515",
"displayName": "Tutorial Sample Document",
"extension": "pdf",
"version": null,
"previousVersionId": null,
"purpose": "Reference",
"size": -1,
"available": false,
"isActive": true,
"createdDateTime": "2021-09-06T15:46:51.5524663Z",
"lastModifiedDateTime": "2021-09-06T15:46:51.5524663Z",
"_links": {
"fileUrl": {
"href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/bf15e508-3b59-49d5-a1b5-ea9ef9d66515.pdf?sv=2018-03-28&sr=b&sig=SeVWEiO2L83DOiSbpBBauY4OhnZaF3QqSIcZOvc6uC8%3D&se=2021-09-06T16%3A46%3A51Z&sp=rcw&rscd=attachment%3B%20filename%3DTutorial%2BSample%2BDocument.pdf"
}
}
}
}
6.2 Upload Document File
Create Document response from the previous step contains a url in _links->fileUrl->href
property. File upload can be done by making a Http PUT request on the provided url via tool such as Postman
or programmatically use Azure libraries to upload file (https://docs.microsoft.com/en-us/rest/api/storageservices/put-blob).
Request Syntax
PUT https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/bf15e508-3b59-49d5-a1b5-ea9ef9d66515.pdf?sv=2018-03-28&sr=b&sig=oft6xWrKourfRl5Nemd03duMS9pmi8zkiaPSE8Pynzw%3D&se=2021-09-08T10%3A51%3A03Z&sp=r&rscd=attachment%3B%20filename%3DTutorial%2BSample%2BDocument.pdf HTTP/1.1
Request Headers
x-ms-blob-type: BlockBlob
Request Body
File Binary Content
6.3 Update Document Instance
The last step in associating a document to component is to notify the system that file has been uploaded. This is achieved by setting 'available' property of the document instance to true.
Make a PUT call to https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/bf15e508-3b59-49d5-a1b5-ea9ef9d66515
endpoint to update the document. Update request expects
request body must contain all the desired properties since this will replace existing document with current document definition.
Request Syntax
PUT https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/bf15e508-3b59-49d5-a1b5-ea9ef9d66515 HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN
Request Body
{
"displayName": "Tutorial Sample Document",
"extension": "pdf",
"version": null,
"previousVersionId": null,
"purpose": "Reference",
"available": true,
"isActive": true
}
Response Headers
HTTP/1.1 200 OK
content-encoding: gzip
content-type: application/json
date: Mon, 6 Sep 2021 15:46:51 GMT
odata-version: 4.0
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
vary: Accept-Encoding
x-correlation-id: 3b4b2e41-3ea6-4597-bda0-6db60a038320
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US
Response Body
{
"document": {
"id": "bf15e508-3b59-49d5-a1b5-ea9ef9d66515",
"displayName": "Tutorial Sample Document",
"extension": "pdf",
"version": null,
"previousVersionId": null,
"purpose": "Reference",
"size": -1,
"available": true,
"isActive": true,
"createdDateTime": "2021-09-06T15:46:51.5524663Z",
"lastModifiedDateTime": "2021-09-06T15:54:47.206787Z",
"_links": {
"fileUrl": {
"href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/bf15e508-3b59-49d5-a1b5-ea9ef9d66515.pdf?sv=2018-03-28&sr=b&sig=SeVWEiO2L83DOiSbpBBauY4OhnZaF3QqSIcZOvc6uC8%3D&se=2021-09-06T16%3A46%3A51Z&sp=rcw&rscd=attachment%3B%20filename%3DTutorial%2BSample%2BDocument.pdf"
}
}
}
}
6.4 Get Component Documents
Make a GET call to https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents
endpoint to get all the documents associated to the component. In this example we will get the documents from the component uploaded in the previous steps. Please note, response contains
four document instances. Three of these documents Design, Thumbnail and TypeCatalog were created and associated to the component during upload activity, while we associated Reference document separately after component is created. You can
download actual files from the url provided in _links->fileUrl-href
property value in each document instance in the response. You can also use following API to get a particular document by it's Id.
Request Syntax
GET https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents HTTP/1.1
Request Headers
Accept: application/vnd.bentley.itwin-platform.v1+json
Content-Type: application/json
Authorization: Bearer JWT_TOKEN
Response Headers
HTTP/1.1 200 OK
content-encoding: gzip
content-type: application/json
date: Wed, 08 Sep 2021 09:51:02 GMT
odata-version: 4.0
request-context: appId=cid-v1:6ee7c246-23f0-43be-ac34-bbbb36da72e9
vary: Accept-Encoding
x-correlation-id: 2c094e5a-b770-4240-9aeb-67bca189263a
x-itwinplatform-media-type: bentley.itwin-platform.v1
x-itwinplatform-region: East US
Response Body
{
"documents": [{
"id": "3938de7f-ebf2-470f-b41a-d314fdb90ec7",
"displayName": "TutorialSampleFile",
"extension": "rfa",
"version": "1",
"previousVersionId": null,
"purpose": "Design",
"size": 749568,
"available": true,
"isActive": true,
"createdDateTime": "2021-09-06T15:17:46.0180736Z",
"lastModifiedDateTime": "2021-09-06T15:17:46.1465969Z",
"_links": {
"associatedDesignDocument": {
"href": null
},
"fileUrl": {
"href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/3938de7f-ebf2-470f-b41a-d314fdb90ec7.rfa?sv=2018-03-28&sr=b&sig=Smec6HJrZCKZGXYARrGkU1RWJuaO3jqmXKs3%2B5irnak%3D&se=2021-09-08T10%3A51%3A03Z&sp=r&rscd=attachment%3B%20filename%3DTutorialSampleFile.rfa"
}
}
}, {
"id": "4f618030-ba8c-4144-872e-c61842c3d90e",
"displayName": "TutorialSampleFile.png",
"extension": "png",
"version": null,
"previousVersionId": null,
"purpose": "Thumbnail",
"size": 0,
"available": true,
"isActive": true,
"createdDateTime": "2021-09-06T15:17:46.2226747Z",
"lastModifiedDateTime": "2021-09-06T15:17:46.3093526Z",
"_links": {
"associatedDesignDocument": {
"href": "https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/3938de7f-ebf2-470f-b41a-d314fdb90ec7"
},
"fileUrl": {
"href": "https://componentscenprodeussa01.blob.core.windows.net/public-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/4f618030-ba8c-4144-872e-c61842c3d90e.png"
}
}
}, {
"id": "f9d9f7ce-a014-4b54-b0a6-e351482ec3a5",
"displayName": "TutorialSampleFile",
"extension": "txt",
"version": null,
"previousVersionId": null,
"purpose": "TypeCatalog",
"size": 760,
"available": true,
"isActive": true,
"createdDateTime": "2021-09-06T15:17:46.4256707Z",
"lastModifiedDateTime": "2021-09-06T15:17:46.510613Z",
"_links": {
"associatedDesignDocument": {
"href": "https://api.bentley.com/library/components/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/documents/3938de7f-ebf2-470f-b41a-d314fdb90ec7"
},
"fileUrl": {
"href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/f9d9f7ce-a014-4b54-b0a6-e351482ec3a5.txt?sv=2018-03-28&sr=b&sig=1yb19XFDPtuEl6rYiFDLuCjz%2FO8a3r7h89KAHdFwvw8%3D&se=2021-09-08T10%3A51%3A03Z&sp=r&rscd=attachment%3B%20filename%3DTutorialSampleFile.txt"
}
}
}, {
"id": "bf15e508-3b59-49d5-a1b5-ea9ef9d66515",
"displayName": "Tutorial Sample Document",
"extension": "pdf",
"version": "1",
"previousVersionId": null,
"purpose": "Reference",
"size": 388077,
"available": true,
"isActive": true,
"createdDateTime": "2021-09-06T15:46:51.5524663Z",
"lastModifiedDateTime": "2021-09-06T15:54:47.206787Z",
"_links": {
"associatedDesignDocument": {
"href": null
},
"fileUrl": {
"href": "https://componentscenprodeussa01.blob.core.windows.net/private-5a7b3c7c-03af-49f0-b1df-115ddc0e0048/57fefe11-df1d-40c7-ae1a-02e233b9a7c7/bf15e508-3b59-49d5-a1b5-ea9ef9d66515.pdf?sv=2018-03-28&sr=b&sig=oft6xWrKourfRl5Nemd03duMS9pmi8zkiaPSE8Pynzw%3D&se=2021-09-08T10%3A51%3A03Z&sp=r&rscd=attachment%3B%20filename%3DTutorial%2BSample%2BDocument.pdf"
}
}
}]
}
Continue learning
Congratulation for completing Upload Component to Catalog tutorial! You should be able to upload components to catalogs and associate additional documents to the components.