Migration guide from iModelHub API to iModels API
iModelHub API is deprecated
Old iModelHub API (accessible https://imodelhubapi.bentley.com/sv1.1/Repositories/*) is deprecated and is in its retirement path. Moving forward, we will not make any new changes into old iModelHub API. Only necessary security-related fixes will be applied. Investments in new features and functionalities are only made in iModels API.
Client packages
Open source TypeScript client packages are available for iModels API:
- @itwin/imodels-client-management - NPM registry, documentation
- @itwin/imodels-client-authoring - NPM registry, documentation
Please check the general documentation for explanation on the difference between the packages.
General API differences
iModels API have been designed to be intuitive for the developer and adhere to modern REST API standards. The new API has extensive documentation on developer portal.
Relationships exchanged for links
Instead of providing very flexible querying mechanism to the client applications new API has been designed either to contain mostly used properties within the queried entity or it contains the links which could be used to query additional information about related entities.
Example
Get user information who created an iModel
Old iModelHub API GET https://imodelhubapi.bentley.com/sv1.1/Repositories/iModel--{iModelId}/iModelScope/iModel?$select=*,HasCreatorInfo-forward-UserInfo.* operation returns the following response body:
{
"instances": [
{
"instanceId": "5e19bee0-3aea-4355-a9f0-c6df9989ee7d",
"schemaName": "iModelScope",
"className": "iModel",
"properties": {
"Description": "Overall model of wind and solar farms in Sun City",
"Name": "Sun City Renewable-energy Plant",
"UserCreated": "42101fba-847a-4f4e-85a8-a4bed89065e4",
"CreatedDate": "2020-10-20T10:51:33.1700000Z",
"Initialized": true,
"DataLocationId": "d69db76c-eb42-435e-8bbd-33e62b4c4908",
"Type": 0,
"Secured": false,
"Shared": false,
"iModelTemplate": "Empty",
"ContextId": "9016df17-962a-4d1a-8e6d-6f0ae7d56c3b"
},
"relationshipInstances": [
{
"instanceId": "",
"schemaName": "iModelScope",
"className": "HasCreatorInfo",
"direction": "forward",
"properties": {},
"relatedInstance": {
"instanceId": "42101fba-847a-4f4e-85a8-a4bed89065e4",
"schemaName": "iModelScope",
"className": "UserInfo",
"properties": {
"Id": "42101fba-847a-4f4e-85a8-a4bed89065e4",
"Name": "Hanson",
"Surname": "Deck",
"Email": "hanson.deck@cohesivecompanies.com",
"IsServiceAccount": false
}
}
}
]
}
]
}
New iModels API Get iModel details (GET https://api.bentley.com/imodels/{id}) operation returns the following response body:
{
"iModel": {
"id": "5e19bee0-3aea-4355-a9f0-c6df9989ee7d",
"displayName": "Sun City Renewable-energy Plant",
"dataCenterLocation": "East US",
"name": "Sun City Renewable-energy Plant",
"description": "Overall model of wind and solar farms in Sun City",
"state": "initialized",
"createdDateTime": "2020-10-20T10:51:33.1700000Z",
"iTwinId": "9016df17-962a-4d1a-8e6d-6f0ae7d56c3b",
"isSecured": false,
"extent": null,
"_links": {
"creator": {
"href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/users/42101fba-847a-4f4e-85a8-a4bed89065e4"
},
"changesets": {
"href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/changesets"
},
"namedVersions": {
"href": "https://api.bentley.com/imodels/5e19bee0-3aea-4355-a9f0-c6df9989ee7d/namedversions"
}
}
}
}
New API returns information in more concise way. Information about the user who created the iModel could be accessed in two ways:
- Following the "creator" link and doing a second request to iModels API.
- If application renders more than 1 iModel then the recommendation is to query Get iModel Users operation, cache the results on the client side and then compare the "creator" link of Get iModel details response with "self" link of each User entity in Get iModel Users response.
Batch requests removed
Batch $changeset requests which were supported by iModelHub API are not supported in iModels API.
Breaking functionality
The table summarizes functionality which has been deprecated and won't be available in the new iModels API or this functionality has been moved to other services.
New operation mappings
The table summarizes a mapping between old iModelHub API endpoint and new iModels API endpoints with a link to the documentation of new API.