DCME Endpoints
DCME Endpoints and Parameters
The DCME endpoints are divided into two groups: DCME endpoints for users and DCME endpoints for admins. All DCME endpoints require TLS to be configured on the Server.
To learn more about the objects relations and how to use them in the API, go to the Objects Relations section.
For more information about data connections, visit the DCM - Server and Data Connection Manager: Server UI help pages.
DCME Endpoints for Users
These endpoints can be used by users with API access:
All API endpoints return individual user data (each user can only see and manage their own connections).
To retrieve a DCM Connection record, use the GET {baseURL}/v3/dcm/connections/{id} endpoint. The endpoint returns all information about the DCM Connection, including the related Data Source and Credentials as well as the sharing information.
Parameters
id (string): Required. Enter the ID of the DCM Connection on which you want to obtain information.
Request Example: cURL
curl --location --request GET 'https://localhost/webapi/v3/dcm/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' \ --header 'Authorization: Bearer BearerTokenGoesHere'
To retrieve a DCM Connection record as it is referenced in workflows, use the GET {baseURL}/v3/dcm/connections/lookup endpoint. The endpoint returns all information about the DCM Connection, including the related Data Source and Credentials as well as the sharing information.
Note
The ConnectionID used in this endpoint is different from the ID used in other DCM endpoints. ID is used to reference various DCM objects, while ConnectionID is only used in workflows to reference DCM Connection for specific users.
Parameters
connectionId (string): Required. Enter the DCM ConnectionID on which you want to obtain information.
Request Example: cURL
curl --location --request GET 'https://localhost/webapi/v3/dcm/connections/lookup?connectionId=d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' \ --header 'Authorization: Bearer BearerTokenGoesHere'
To create or update a DCM Connection, use the POST {baseURL}/v3/dcm/connections endpoint.
Single endpoint serves both create and update functions, differentiated by whether object IDs are included in the request. The reuse of existing data sources or credentials is currently unsupported when creating new connections.
Parameters
upsertConnectionContract (string): Required. DCM Connection is a combination of a data source (describing the target instance host) and credentials (for example, username and password) by defining the possible schema combination.
id (string): Optional. Enter a connection ID if you wish to update an existing connection. Skip if you wish to create a new connection.
name (string): Required. Enter the name of your connection.
schemaName (string): Required. Enter a connection schema name you’d like to use. The schema defines the required parameters of the connection as well as the data source and credentials schemas allowed to be used for that connection.
allowInSdks (boolean): Optional.
parameters (object): Required. Various parameters might be required based on the schemaName selected.
dataSource (object): Required. The data source used for the connection, describing the data source instance host and additional parameters, as seen in DCM UI.
object (object): Required.
id (string): Enter a data source ID if you wish to update an existing connection. Skip if you wish to create a new connection. Using an existing data source when creating new connections is currently unavailable.
name (string): Required. Enter a name for the data source.
schemaName (string): Required. Enter the schema name of the selected data source.
additional schema-specific parameters: depending on the schema used, you’ll be required to provide additional data source parameters.
credentials (string): Optional, depending on the selected schemaName in the upsertConnectionContract. Some connections may not require any credentials, while others may have multiple nested objects (slots).
main (object): Optional (see above). This main is just one (most common) credential slot name. It can however be named differently or there might be multiple credential slots for the connection depending on what is defined in the connection schema.
id (string): Enter a credential ID if you wish to update an existing connection. Skip if you wish to create a new connection. Using an existing credential when creating new connections is currently unavailable.
name (string): Required. Enter the name of your credential.
schemaName (string): Required. Enter the schema name of the selected credential.
additional schema-specific parameters: depending on the schema used, you’ll be required to provide additional data source parameters.
Request Example: cURL
curl --location --request POST 'https://localhost/webapi/v3/dcm/connections' \ --header 'Authorization: Bearer BearerTokenGoesHere' \ --header "Content-Type: application/json" \ --data '{"Name":"MSSQL DEV Admin","SchemaName":"database-odbc-dsn-mssql","Parameters":{},"DataSource":{"object":{"name":"SQL Server DEV","SchemaName":"database-odbc-dsn-mssql","parameters":{"dsn":"sql server"}}},"Credentials":{"main":{"object":{"name":"SQL Server Admin Credentials","SchemaName":"username_password","parameters":{},"userName":"admin","secrets":{"password":{"value":{"text":"password"},"Parameters":{}}}}}}}'
To delete a DCM Connection, use the DELETE {baseURL}/v3/dcm/connections/{id} endpoint. The data source and credentials will be deleted as well unless they are used in any other connection.
Parameters
id (string): Required. Enter the DCM Connection ID you want to delete.
Request Example: cURL
curl --location --request DELETE 'https://localhost/webapi/v3/dcm/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' \ --header 'Authorization: Bearer BearerTokenGoesHere'
DCME Endpoints for Admins
Endpoints that can be used by Curators with API access:
All admin API endpoints return all data available on the Server across all users, regardless of ownership.
To retrieve a DCM Connection record, use the GET {baseURL}/v3/dcm/admin/connections/{objectId} endpoint.
Parameters
objectId (string): Required. Enter the DCM Connection ID you want to get information about.
Request Example: cURL
curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' \ --header 'Authorization: Bearer BearerTokenGoesHere'
To retrieve a list of all DCM Connection records present on the Server, use the GET {baseURL}/v3/dcm/admin/connections endpoint.
Parameters
Both parameters are filters that can be combined. Using connectionId and visibleBy together will return the connection with the ConnectionID specified, visible by the specified user.
connectionId (string): Optional. Filters connections by its connectionID, as referenced from a workflow. Multiple connections can be returned for a single connectionID, if the connection is shared for collaboration.
visibleBy (string): Optional. Enter user ID. If present, it filters the results to the same result as for all connections available to the specified user.
Request Example: cURL
curl --location --request GET 'https://localhost/webapi/v3/dcm/admin/connections?connectionId=d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3&visibleBy=bc7cb7b47c33' \ --header 'Authorization: Bearer BearerTokenGoesHere'
To create or update a DCM Connection record on behalf of a user, use the POST {baseURL}/v3/dcm/admin/connections endpoint.
Parameters
upsertConnectionContract (string): Required.
id (string): Optional. Enter a connection ID if you wish to update an existing connection. Skip if you wish to create a new connection.
ownerId (string): Required.
When creating a DCM Connection, enter the ID of the user on behalf of which the connection shall be created.
When updating a DCM Connection, you must also enter the ownerId even if you don't want to change it. For more information how to get an ownerID, go to Retrieve a DCM Connection Record or Retrieve a List of DCM Connection Records.
name (string): Required. Enter the name of your connection.
schemaName (string): Required. Enter a connection schema name you’d like to use. The schema defines the required parameters of the connection as well as the data source and credentials schemas allowed to be used for that connection.
allowInSdks (boolean): Optional.
parameters (object): Required. Various parameters might be required based on the schemaName selected.
dataSource (object): Required. The data source used for the connection
object (object): Required.
id (string): Enter a data source ID if you're updating an existing connection. Skip if you wish to create a new connection. Using an existing data source when creating new connections is currently unavailable.
name (string): Required. Enter a name for the data source.
schemaName (string): Required. Enter the schema name of the selected data source.
additional schema-specific parameters: depending on the schema used, you’ll be required to provide additional data source parameters.
credentials (string): Optional, depending on the selected schemaName in the upsertConnectionContract. Some connections may not require any credential, while others may have multiple.
main (object): Optional (see above).
id (string): Enter a credential ID if you’re updating an existing connection. Skip if you wish to create a new connection. Using an existing credential when creating new connections is currently unavailable.
name (string): Required. Enter the name of your credential.
schemaName (string): Required. Enter the schema name of the selected credential.
additional schema-specific parameters: depending on the schema used, you’ll be required to provide additional credential parameters.
Request Example: cURL
curl --location --request POST 'https://localhost/webapi/v3/dcm/connections' \ --header 'Authorization: Bearer BearerTokenGoesHere' \ --header "Content-Type: application/json" \ --data '{"Name":"MSSQL DEV Admin","onwerId":"1b4bc56d489d9543a",SchemaName":"database-odbc-dsn-mssql","Parameters":{},"DataSource":{"object":{"name":"SQL Server DEV","SchemaName":"database-odbc-dsn-mssql","parameters":{"dsn":"sql server"}}},"Credentials":{"main":{"object":{"name":"SQL Server Admin Credentials","SchemaName":"username_password","parameters":{},"userName":"admin","secrets":{"password":{"value":{"text":"password"},"Parameters":{}}}}}}}'
To delete a DCM Connection record, use the DELETE {baseURL}/v3/dcm/admin/connections/{objectId} endpoint. The data source and credentials will be deleted as well unless they are used in any other connection.
Parameters
objectId (string): Required. Enter the DCM Connection ID you want to delete.
Request Example: cURL
curl --location --request DELETE 'https://localhost/webapi/v3/dcm/admin/connections/d8cc5fca-86cc-4e7e-93a3-d500cca9a3f3' \ --header 'Authorization: Bearer BearerTokenGoesHere'
Objects Relations
If you are creating a DCM Connection, you can use created objects as follows:
Object created:
"id" (for example, "id": "c128cc5fca-86cc-4e7e-93a3-d500cca9a3f3")
“connectionId” (for example, "id": "c0332423423-86cc-4e7e-93a3-d500cca9a3f3")
You can use it as:
id if you want to Retrieve a DCM Connection Record
connectionId if you want to Retrieve a DCM Connection as Referenced in Workflows
id if you want to Share a DCM Connection with Specified Users and Groups
id if you want to Update a DCM Connection
id if you want to Delete a DCM Connection
id if you want to Unshare a DCM Connection
Admin:
id if you want to Retrieve a DCM Connection Record
ownerId (userId) if you want to Create a DCM Connection on Behalf of a User
id if you want to Update a DCM Connection on Behalf of a User
id if you want to Unshare a DCM Connection Shared for Execution
id if you want to Unshare a DCM Connection Shared for Collaboration
id if you want to Delete a DCM Connection