Create iTwin repository - iTwins

iTwins

Download API definition:

POST https://dev-api.bentley.com/itwins/{iTwinId}/repositories

Registers a new repository for the iTwin. A repository is any service or data source that contains data for the iTwin.

The following Classes/SubClasses of repositories are supported.

GeographicInformationSystem
- WebMapService
- WebMapTileService
- ArcGIS
- UrlTemplate
Construction
- Performance
Subsurface
- EvoWorkspace

A common use case is to register 3rd party imagery providers and associate them with the iTwin so they can be used when displaying iTwin data in a map view.

The Repositories API will accept a payload containing the following information: subclass, uri, displayName, authentication parameters, and options. All subclasses support a queryParameters object within the options. Any additional properties within options are specific to the subclass. The API will validate the payload to ensure any required fields are present and conform to the schema for the specified subclass. The authenticationand options properties are optional since some repositories may only need a uri to access data.

An example of creating an UrlTemplate imagery repository can be seen below.

{
  "class": "GeographicInformationSystem",
  "subClass": "UrlTemplate",
  "displayName": "My xyz template server",
  "uri": "http://basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
  "authentication": {
    "type": "Header",
    "key": "X-Api-Key",
    "value": "mySecretApiKey"
  },
  "options": {
    "queryParameters": {
        "apiVersion": "1.5.1"
    },
    "minimumLevel": 10,
    "maximumLevel": 20
  }
}

The information above will inform the client that when they call the uri, they need to add a header X-Api-Key = mySecretApiKey for authorization and a query parameter apiVersion = 1.5.1 to ensure the correct version is used. The minimumLevel and maximumLevel properties are additional values needed to display the data. These properties are only returned for the UrlTemplate subclass and can be can be passed to the CesiumJS UrlTemplateImageryProvider

Since the schema for options field will correspond to the class/subclass, the client is responsible for knowing which properties to expect in the options and how to apply them to the appropriate imagery provider. While the returned options are not 1:1 with the constructor values in each corresponding CesiumJS imagery provider, the options and authentication are generic enough so that all the necessary information should be available to instantiate the necessary provider.

The correspond CesiumJS options can be found at the following links for the imagery providers we intend to support:

Here is another example of a registering a WMS map server, which has no additional custom options besides query parameters.

{
  "id": "547d397a-9921-4e4f-a7a2-c47fc19219b0",
  "class": "GeographicInformationSystem",
  "subClass": "WebMapService",
  "name": "Local aquifers"
  "uri": "https://map.gsa.state.al.us/arcgis/services/ALWaterSTAR/ALWaterSTAR/MapServer/WMSServer",
  "authentication": {
    "type": "QueryParameter",
    "key": "apiKey,
    "value": "mySecretApiKey"
  },
  "options": {
    "queryParameters": {
      "format": "image/png",
      "bbox": "-145.15104058007,21.731919794922,-57.154894212888,58.961058642578"
    }
  }
}

Authentication

Requires Authorization header with valid Bearer token for scope itwin-platform.

For more documentation on authorization and how to get access token visit OAUTH2 Authorization page.

Authorization

The user must have the itwins_modify permission in order to register a repository for the iTwin.

Organization Administrators automatically get the itwins_modify permission for every iTwin in their Organization.

Organization Administrators are power users for all iTwins owned by their organization. They will be able to create, modify or delete any iTwin. Example: john.doe@example.com is an Organization Administrator that works for Example Industries. John will be able to create iTwins and those iTwins will belong to Example Industries. John and any other Organization Administrator for Example Industries will be able to update or delete the iTwin. Any user (an employee of Example Industries, or an external participant) can be invited to collaborate on the iTwin.

An Organization Administrator must have at least one of the following roles assigned in User Management: Account Administrator, Co-Administrator, or CONNECT Services Administrator. For more information about User Management please visit our Bentley Communities Licensing, Cloud, and Web Services wiki page.

Request

Request parameters

iTwinId

Yes

The iTwin Id

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

Setting to application/vnd.bentley.itwin-platform.v1+json is recommended.

Request body

iTwin-repository-create

class

iTwinRepositoryClass

Yes

The repository class.

subClass

iTwinRepositorySubClass

The repository subclass.

displayName

String

The repository name that should be displayed to the user.

uri

String

Yes

The uri for the repository.

authentication

AuthenticationInfo

Some repositories require additional authorization information. If there is authentication information, then inspect the authentication.type property to determine how to handle it. You will need to add a header, query parameter or use basic auth. In some cases, the authentication info will expire (usually after 1 hour).

options

One of: GIS-General-Options GIS-UrlTemplate-Options

Additional options that are needed when requesting data from the repository.

Example

json

{
    "class": "GeographicInformationSystem",
    "subClass": "UrlTemplate",
    "displayName": "My xyz template server",
    "uri": "http://basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
    "authentication": {
        "type": "Header",
        "key": "X-Api-Key",
        "value": "mySecretApiKey"
    },
    "options": {
        "queryParameters": {
            "apiVersion": "1.5.1"
        },
        "minimumLevel": 10,
        "maximumLevel": 20
    }
}

Response

Response 201 Created

Repository successfully created.

json

{
    "repository": {
        "id": "e2ecdff7-2802-48bf-9bfa-d418c740c8cd",
        "class": "GeographicInformationSystem",
        "subClass": "UrlTemplate",
        "displayName": "My xyz template server",
        "uri": "http://basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
        "authentication": {
            "type": "Header",
            "key": "X-Api-Key",
            "value": "mySecretApiKey"
        },
        "options": {
            "queryParameters": {
                "apiVersion": "1.5.1"
            },
            "minimumLevel": 10,
            "maximumLevel": 20
        }
    }
}

Response 401 Unauthorized

This response indicates that request lacks valid authentication credentials. Access token might not been provided, issued by the wrong issuer, does not have required scopes or request headers were malformed.

json

{
    "error": {
        "code": "HeaderNotFound",
        "message": "Header Authorization was not found in the request. Access denied."
    }
}

Response 403 Forbidden

The user is not authorized to create an iTwin Repository.

json

{
    "error": {
        "code": "InsufficientPermissions",
        "message": "The user has insufficient permissions for the requested operation."
    }
}

Response 404 Not Found

This response indicates that the specified repository was not found.

json

{
    "error": {
        "code": "iTwinNotFound",
        "message": "Requested iTwin is not available."
    }
}

Response 409 Conflict

iTwin Repository with the same name already exists.

json

{
    "error": {
        "code": "iTwinRepositoryExists",
        "message": "The specified iTwin Repository already exists."
    }
}

Response 422 Unprocessable Entity

Invalid request to create an iTwin Repository. Review the 'Field Values' section near the top of this page.

json

{
    "error": {
        "code": "InvalidiTwinsRequest",
        "message": "Cannot add iTwin Repository.",
        "details": [{
                "code": "InvalidValue",
                "message": "Class value is incorrect.",
                "target": "class"
            },
            {
                "code": "InvalidValue",
                "message": "SubClass value is incorrect.",
                "target": "subClass"
            },
            {
                "code": "MissingRequiredProperty",
                "message": "A required property is missing or empty.",
                "target": "class"
            },
            {
                "code": "MissingRequiredProperty",
                "message": "A required property is missing or empty.",
                "target": "displayName"
            },
            {
                "code": "InvalidValue",
                "message": "DisplayName cannot be more than 200 characters.",
                "target": "displayName"
            },
            {
                "code": "MissingRequiredProperty",
                "message": "A required property is missing or empty.",
                "target": "uri"
            },
            {
                "code": "InvalidValue",
                "message": "Options are not valid.",
                "target": "options"
            },
            {
                "code": "InvalidValue",
                "message": "Key must be defined for authentication type {Type}.",
                "target": "key"
            },
            {
                "code": "InvalidValue",
                "message": "Value must be defined for authentication type {Type}.",
                "target": "value"
            },
            {
                "code": "InvalidValue",
                "message": "Username must be defined for authentication type basic.",
                "target": "username"
            },
            {
                "code": "InvalidValue",
                "message": "Password must be defined for authentication type basic.",
                "target": "password"
            },
            {
                "code": "InvalidValue",
                "message": "minimumLevel must be between 0 and 24 inclusive.",
                "target": "minimumlevel"
            },
            {
                "code": "InvalidValue",
                "message": "maximumLevel must be between 0 and 24 inclusive.",
                "target": "maximumlevel"
            }
        ]
    }
}

Response 429 Too many requests

This response indicates that the client sent more requests than allowed by this API for the current tier of the client.

json

{
    "error": {
        "code": "RateLimitExceeded",
        "message": "The client sent more requests than allowed by this API for the current tier of the client."
    }
}

Response headers

retry-after

Number of seconds to wait until client is allowed to make more requests.

Definitions

iTwin-repository-response

repository

iTwin-repository

json

{
    "type": "object",
    "properties": {
        "repository": {
            "$ref": "#/components/schemas/iTwin-repository"
        }
    },
    "required": [
        "repository"
    ],
    "additionalProperties": false
}

iTwin Repository Class

The class of your iTwin repository.

RealityData

String

iModels

String

Storage

String

Forms

String

Construction

String

GeographicInformationSystem

String

CesiumCuratedContent

String

SensorData

String

Subsurface

String

GeospatialFeatures

String

PdfPlansets

String

json

{
    "type": "string",
    "title": "iTwin Repository Class",
    "description": "The class of your iTwin repository.",
    "enum": [
        "RealityData",
        "iModels",
        "Storage",
        "Forms",
        "Construction",
        "GeographicInformationSystem",
        "CesiumCuratedContent",
        "SensorData",
        "Subsurface",
        "GeospatialFeatures",
        "PdfPlansets"
    ]
}

iTwin Repository SubClass

The subclass of your iTwin repository.

WebMapService

String

WebMapTileService

String

ArcGIS

String

UrlTemplate

String

Performance

String

EvoWorkspace

String

json

{
    "type": "string",
    "title": "iTwin Repository SubClass",
    "description": "The subclass of your iTwin repository.",
    "enum": [
        "WebMapService",
        "WebMapTileService",
        "ArcGIS",
        "UrlTemplate",
        "Performance",
        "EvoWorkspace"
    ]
}

iTwin-repository

String

The iTwin repository id.

class

iTwinRepositoryClass

The repository class.

subClass

iTwinRepositorySubClass

The repository subclass.

displayName

String

The repository name that can be displayed to the user.

uri

String

The uri for the repository.

capabilities.resources

ResourcesCapability

authentication

AuthenticationInfo

options

One of: GIS-General-Options GIS-UrlTemplate-Options

Additional options that are needed when requesting data from the repository.

json

{
    "type": "object",
    "properties": {
        "id": {
            "type": "string",
            "description": "The iTwin repository id."
        },
        "class": {
            "$ref": "#/components/schemas/iTwinRepositoryClass",
            "description": "The repository class."
        },
        "subClass": {
            "$ref": "#/components/schemas/iTwinRepositorySubClass",
            "description": "The repository subclass."
        },
        "displayName": {
            "type": "string",
            "description": "The repository name that can be displayed to the user."
        },
        "uri": {
            "type": "string",
            "description": "The uri for the repository."
        },
        "capabilities": {
            "type": "object",
            "required": [
                "resources"
            ],
            "properties": {
                "resources": {
                    "$ref": "#/components/schemas/ResourcesCapability"
                }
            },
            "description": "Links to additional capabiblies provided by the repository. Currently, only the [resources](https://developer.bentley.com/apis/itwins/operations/get-repository-resources/) capability is suported. It is a read only value returned for certain classes.",
            "additionalProperties": false
        },
        "authentication": {
            "$ref": "#/components/schemas/AuthenticationInfo",
            "description": "Some repositories require additional authorization information. If there is authentication information, then inspect the `authentication.type` property to determine how to handle it. You will need to add a header, query parameter or use basic auth. In some cases, the authentication info will expire (usually after 1 hour)."
        },
        "options": {
            "oneOf": [
                {
                    "$ref": "#/components/schemas/GIS-General-Options"
                },
                {
                    "$ref": "#/components/schemas/GIS-UrlTemplate-Options"
                }
            ],
            "description": "Additional options that are needed when requesting data from the repository."
        }
    },
    "additionalProperties": false
}

iTwin-repository-create

class

iTwinRepositoryClass

The repository class.

subClass

iTwinRepositorySubClass

The repository subclass.

displayName

String

The repository name that should be displayed to the user.

uri

String

The uri for the repository.

authentication

AuthenticationInfo

options

One of: GIS-General-Options GIS-UrlTemplate-Options

Additional options that are needed when requesting data from the repository.

json

{
    "type": "object",
    "properties": {
        "class": {
            "$ref": "#/components/schemas/iTwinRepositoryClass",
            "description": "The repository class."
        },
        "subClass": {
            "$ref": "#/components/schemas/iTwinRepositorySubClass",
            "description": "The repository subclass."
        },
        "displayName": {
            "type": "string",
            "description": "The repository name that should be displayed to the user."
        },
        "uri": {
            "type": "string",
            "description": "The uri for the repository."
        },
        "authentication": {
            "$ref": "#/components/schemas/AuthenticationInfo",
            "description": "Some repositories require additional authorization information. If there is authentication information, then inspect the `authentication.type` property to determine how to handle it. You will need to add a header, query parameter or use basic auth. In some cases, the authentication info will expire (usually after 1 hour)."
        },
        "options": {
            "oneOf": [
                {
                    "$ref": "#/components/schemas/GIS-General-Options"
                },
                {
                    "$ref": "#/components/schemas/GIS-UrlTemplate-Options"
                }
            ],
            "description": "Additional options that are needed when requesting data from the repository."
        }
    },
    "additionalProperties": false,
    "example": {
        "class": "GeographicInformationSystem",
        "subClass": "WebMapTileService",
        "url": "https://developer.bentley.com"
    },
    "required": [
        "class",
        "uri"
    ]
}

GIS-General-Options

Options that may be needed to query or display data from the repository.

queryParameters

Object

Query parameters that should be added to the uri when making a request.

json

{
    "type": "object",
    "properties": {
        "queryParameters": {
            "type": "object",
            "additionalProperties": {
                "type": "string"
            },
            "description": "Query parameters that should be added to the uri when making a request."
        }
    },
    "required": [
        "queryParameters"
    ],
    "description": "Options that may be needed to query or display data from the repository.",
    "additionalProperties": false
}

GIS-UrlTemplate-Options

Options that can be used in the construtor of the UrlTemplateImageryProvider. Also includes the general options that allow you to specify query parameters if needed.

queryParameters

Object

Query parameters that should be added to the uri when making a request.

minimumLevel

Integer

Minimum level-of-detail that can be requested.

maximumLevel

Integer

Maximum level-of-detail that can be requested.

json

{
    "type": "object",
    "properties": {
        "queryParameters": {
            "type": "object",
            "additionalProperties": {
                "type": "string"
            },
            "description": "Query parameters that should be added to the uri when making a request."
        },
        "minimumLevel": {
            "type": "integer",
            "description": "Minimum level-of-detail that can be requested."
        },
        "maximumLevel": {
            "type": "integer",
            "description": "Maximum level-of-detail that can be requested."
        }
    },
    "required": [
        "minimumLevel",
        "maximumLevel"
    ],
    "description": "Options that can be used in the construtor of the [UrlTemplateImageryProvider](https://cesium.com/learn/cesiumjs/ref-doc/UrlTemplateImageryProvider.html). Also includes the general options that allow you to specify query parameters if needed.",
    "additionalProperties": false
}

ResourcesCapability

uri

String

A uri containing the endpoint that will return the list of resources in the repository.

json

{
    "type": "object",
    "properties": {
        "uri": {
            "type": "string",
            "description": "A uri containing the endpoint that will return the list of resources in the repository."
        }
    },
    "additionalProperties": false
}

AuthenticationInfo

Contains all of the information needed to authenticate to the specified API. For example, if type=Header then add a header using key=value.

type

String

One of a server-defined set of error codes.

key

String

The key to use for Header or QueryParameter auth types.

value

String

The value to use for Header or QueryParameter auth types.

username

String

The value to use for Basic auth type.

password

String

The value to use for Basic auth type.

json

{
    "type": "object",
    "description": "Contains all of the information needed to authenticate to the specified API. For example, if type=Header then add a header using key=value.",
    "properties": {
        "type": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "key": {
            "type": "string",
            "description": "The key to use for Header or QueryParameter auth types."
        },
        "value": {
            "type": "string",
            "description": "The value to use for Header or QueryParameter auth types."
        },
        "username": {
            "type": "string",
            "description": "The value to use for Basic auth type."
        },
        "password": {
            "type": "string",
            "description": "The value to use for Basic auth type."
        }
    },
    "required": [
        "type"
    ],
    "additionalProperties": false
}

Error

Contains error information.

code

String

One of a server-defined set of error codes.

message

String

A human-readable representation of the error.

target

String, null

The target of the error.

json

{
    "type": "object",
    "description": "Contains error information.",
    "properties": {
        "code": {
            "type": "string",
            "description": "One of a server-defined set of error codes."
        },
        "message": {
            "type": "string",
            "description": "A human-readable representation of the error."
        },
        "target": {
            "type": "string",
            "description": "The target of the error.",
            "nullable": true
        }
    },
    "required": [
        "code",
        "message"
    ],
    "additionalProperties": true
}

Error Response

Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.

error

Error

Error information.

json

{
    "type": "object",
    "title": "Error Response",
    "description": "Gives details for an error that occurred while handling the request. Note that clients MUST NOT assume that every failed request will produce an object of this schema, or that all of the properties in the response will be non-null, as the error may have prevented this response from being constructed.",
    "properties": {
        "error": {
            "description": "Error information.",
            "$ref": "#/components/schemas/Error"
        }
    },
    "required": [
        "error"
    ],
    "additionalProperties": false
}

Was this page helpful?