Update iTwin Repository - iTwins

iTwins

Download API definition:

This operation is a Technical Preview and is available for testing purposes only. Do not use in production.

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

This endpoint allows you to update an existing repository for the following Classes/SubClasses.

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

All properties are optional. Only the properties that are specified in the request body will be updated. If you need to remove all options or authentication informatino then you can set them to null in the request body. Uri and displayName cannot be set to null. Class, SubClass, and Id cannot be changed.

This is an example of updating the displayName only.

{
  "displayName": "My xyz template server - updated",    
}

This is an example of updating the Uri and removing all options.

{
 "uri": "http://basemaps.cartocdn.com/light_all/updated/{z}/{x}/{y}.png",
 "options": null
}

If you want to update the authentication or options then you must specify the entire object. For example, you cannot just update the authentication.password or options.queryParameters. You must specify the entire authentication or options object.

This is an example of updating the api key. You must specify the entire authentication object.

{
 "authentication": {
   "type": "Header",
   "key": "X-Api-Key",
   "value": "myNewSecretApiKeyUpdated"
 }
}

This is an example of updating the displayName and options.maximumLevel. You must specify all the options properties.

{
 "displayName": "My xyz template server",
 "options": {
   "queryParameters": {
       "apiVersion": "1.5.1"
   },
   "minimumLevel": 5,
   "maximumLevel": 10
 }
}

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 modify 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

repositoryId

Yes

The repository Id

Request headers

Authorization

Yes

OAuth access token with itwin-platform scope

Yes

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

A iTwin instance with the fields that should be updated. ReadOnly fields should not be included.

Request body

iTwin-repository-update

displayName

String

The repository name that should be displayed to the user.

uri

String

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

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

Response

Response 200 OK

json

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

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 has insufficient permissions for the requested operation.

json

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

Response 404 Not Found

This response indicates that one of the associated entities could not be found.

json

{
    "error": {
        "code": "iTwinRepositoryNotFound",
        "message": "Requested iTwin Repository 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 update an iTwin Repository. Review the 'Field Values' section near the top of this page.

json

{
    "error": {
        "code": "InvalidiTwinsRequest",
        "message": "Cannot update iTwin Repository.",
        "details": [{
                "code": "InvalidValue",
                "message": "Uri cannot be null or empty.",
                "target": "uri"
            },
            {
                "code": "InvalidValue",
                "message": "Uri cannot be more than 2000 characters.",
                "target": "uri"
            },
            {
                "code": "InvalidValue",
                "message": "DisplayName cannot be null or empty.",
                "target": "displayName"
            },
            {
                "code": "InvalidValue",
                "message": "DisplayName cannot be more than 200 characters.",
                "target": "displayName"
            },
            {
                "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-update

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": {
        "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": {
        "displayName": "Updated Name",
        "url": "https://developer.bentley.com"
    }
}

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?