Introduction

Use IBM Master Data Connect to power your business applications with trusted master data. The Master Data Connect service on IBM Cloud Pak for Data helps you to capitalize on the benefits that master data brings to business applications. Master Data Connect enables you to provide geographically distributed users with fast, scalable, and concurrent access to your organization's most trusted data source.

To optimize mobile and online applications, organizations must provide timely and efficient access to their trusted master data, including support for geographically distributed data centers. Master Data Connect uses a state of the art RESTful API to meet these requirements. You can use Master Data Connect to

  • Provision your master data close to your consumption points around the globe.
  • Populate Master Data Connect with record data from your IBM InfoSphere Master Data Management Advanced Edition or Standard Edition instance by using API commands.
  • Get access to your master data by using the RESTful API including text search and graph search with gremlin query capabilities.

For details about Master Data Connect on Cloud Pak for Data, see the service's documentation in the IBM Cloud Pak for Data Product Hub.

Service endpoint

The Master Data Connect service endpoint is based on your Cloud Pak for Data deployment URL.

https://<CPD_CLUSTER_HOST>:<PORT>/mdm/cache/

For example, if your instance is deployed at https://www.example.com:31843, you can access the Master Data Connect APIs at https://www.example.com:31843/mdm/cache/.

Additionally, you can access, discover, and run API commands with the Swagger UI API Explorer at the URL https://<CPD_CLUSTER_HOST>:<PORT>/api-cache/explorer. For example, using the same instance host as in the previous example, you can access the Swagger UI API Explorer for Master Data Connect APIs at https://www.example.com:31843/api-cache/explorer.

Example

curl -H "Authorization: Bearer {token}" -X {request_method} "https://<CPD_CLUSTER_HOST>:<PORT>/mdm/cache/<METHOD>"

Error handling

This API uses standard HTTP response codes to indicate whether a method completed successfully. A 200 response indicates success. A 400 type response indicates a failure, and a 500 type response indicates an internal system error.

HTTP Error Code Description Recovery
200 Success The request was successful.
202 Accepted The request was understood and accepted. Processing will continue in the background.
202 No Content The request was successful. No content will be returned.
400 Bad Request The input parameters in the request are either incomplete or in the wrong format. Be sure to include all required parameters in your request.
401 Unauthorized You are not authorized to make this request. Log in to IBM Cloud and try again. If this error persists, contact the account owner to check your permissions.
403 Forbidden The supplied authentication is not authorized to access the resource. Contact the account owner to check your permissions.
404 Not Found The requested resource could not be found.
405 Method Not Allowed The request is not allowed for the requested resource.
408 Request Timeout The connection to the server timed out. Wait a few minutes, then try again.
409 Conflict The entity is already in the requested state.
410 Gone The requested resource is no longer available and will not become available in the future.
500 Internal Server Error Your request could not be processed due to an internal error. Check server logs for more details.
503 Service Unavailable The requested service is currently unavailable. Wait a few minutes and try again.

ErrorResponse

Name Description
code

integer
HTTP error code.
error

string
Human-readable error string, like 'Invalid image file'.

ErrorAuthentication

Name Description
status

string
The status of error.
statusInfo

string
Information about the error.

ErrorHTML

Name Description
Error

string
HTML description of the error.
statusInfo

string
Information about the error.

ErrorInfo

Information about what might have caused a failure, such as an image that is too large. Not returned when there is no error.

Name Description
code

integer
HTTP status code.
description

string
Human-readable error description. For example, File size limit exceeded.
error_id

string
Codified error string. For example, limit_exceeded.

The Java SDK generates an exception for any unsuccessful method invocation. All methods that accept an argument can also throw an IllegalArgumentException.

Exception Description
IllegalArgumentException An invalid argument was passed to the method.

When the Java SDK receives an error response from the Master Data Connect service, it generates an exception containing the following fields:

Field Description
statusCode The HTTP status code returned
message A message describing the error

The Python SDK generates an exception for any unsuccessful method invocation. When the Python SDK receives an error response from the Master Data Connect service, it generates an exception containing the following fields:

Field Description
code The HTTP status code returned
message A message describing the error
info A dictionary of additional information about the error

Example error handling

try {
    // Invoke a Master Data Connect method
} catch (NotFoundException e) {
    // Handle Not Found (404) exception
} catch (RequestTooLargeException e) {
    // Handle Request Too Large (413) exception
} catch (ServiceResponseException e) {
    // Base class for all exceptions caused by error responses from the service
    System.out.println("Service returned status code " + e.getStatusCode() + ": " + e.getMessage());
}

Authentication

To authenticate to the API, you must pass an IBM Cloud Pak for Data service instance token in an Authorization header. You can retrieve the instance token by viewing the service instance details in the Cloud Pak for Data web interface or using the the /zen-data/v2/serviceInstance/users API.

Service instance tokens expire 20 minutes after creation.

To obtain a service instance token and authorize your Master Data Connect API calls, complete the following steps:

Granting users access to Master Data Connect

You can grant users access to Master Data Connect in two ways:

  • With the Cloud Pak for Data web interface.
  • With the the /zen-data/v2/serviceInstance/users API.

Users must be assigned one of the following roles:

  • MDC-Manager - Perform manager operations such as creating traversal templates, and updating the logical model. The MDC-Manager role also includes the same privileges as the MDC-Writer role.
  • MDC-Writer - Perform write operations such as loading data. The MDC-Writer role also includes the same privileges as the MDC-Reader role.
  • MDC-Reader - Perform read operations such as running searches or running graph queries by using traversal templates.

Granting access to users with the Cloud Pak for Data web interface

To grant access to users by using the Cloud Pak for Data web interface:

  1. Log into the Cloud Pak for Data web interface.
  2. Navigate to My Instances, then select the specified instance.
  3. Click the Manage access option.
  4. If the user is not listed on the manage access page:
    • Select the Add users option.
    • Select the specified users and select the role of MDC-Reader, MDC-Writer, or MDC-Manager.
    • Click Add to complete the role assignment.
  5. If the user is already listed on the manage access page:
    • Hover over the specified user and select the Edit option.
    • Select the role of MDC-Reader, MDC-Writer, or MDC-Manager.
    • Click Save to complete the role assignment.

Granting access to users with the Cloud Pak for Data API

To grant access to users by using the /zen-data/v2/serviceInstance/users API, first run the following curl command to get all users present in Cloud Pak for Data:

curl -k -X GET https://<CPD_CLUSTER_HOST>:<PORT>/icp4d-api/v1/users -H 'authorization: Bearer <PLATFORM_TOKEN>'

Then use the /zen-data/v2/serviceInstance/users API to assign the users roles while granting them access by running the following curl command:

curl -k -X POST \
  https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v2/serviceInstance/users/ \
  -H 'Authorization: Bearer <PLATFORM_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
   "serviceInstanceID":"<PROVISIONED_INSTANCE_ID>",
   "users":[
      {
         "display_name":"<DISPLAY_NAME>",
         "role":"<MDC_ROLE>",
         "uid":"<USER_ID>",
         "username":"<USER_NAME>"
      }
   ]
}'

Replace the following values in the above curl command:

  • <CPD_CLUSTER_HOST>:<PORT> - your Cloud Pak for Data cluster host and port.
  • <PLATFORM_TOKEN> - the user platform token.
  • <PROVISIONED_INSTANCE_ID> - the instance ID of your provisioned instance.
  • <DISPLAY_NAME>, <USER_ID>, and <USER_NAME> - the user display name, user ID, and user name obtained from the /zen-data/v2/serviceInstance/users API.
  • <MDC_ROLE> - the desired Master Data Connect role: MDC-Reader, MDC-Writer, or MDC-Manager.
curl -k -X POST   https://ibm-nginx-svc-lite.apps.cpd-lb.ibm.com/zen-data/v2/serviceInstance/users/   -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6ImFkbWluIiwic3ViIjoiYWRtaW4iLCJpc3MiOiJLTk9YU1NPIiwiYXVkIjoiRFNYIiwicm9sZSI6IkFkbWluIiwicGVybWlzc2lvbnMiOlsiYWRtaW5pc3RyYXRvciIsImNhbl9wcm92aXNpb24iXSwidWlkIjoiMTAwMDMzMDk5OSIsImF1dGhlbnRpY2F0b3IiOiJkZWZhdWx0IiwiZGlzcGxheV9uYW1lIjoiYWRtaW4iLCJpYXQiOjE1NzQzNjI2MDksImV4cCI6MTU3NDQwNTgwOX0.olm53bABcdVE6J9vi-VbRU13cr3B0MKRMVq6D4H-W7tXPZOLDvdsIKhCpW0aBi_iryE1sSgIdIb663RmW_nws2wxlpYWHtvigPwY5OVsr8dIA_wRlsCC96JnVa0GB0adM7U-qSfEruTTWZTLxL-gr4EucUXSZ84aii9ukMtN4VUDTvKsa9xJtnQY4W3owdezRzbG_6UkcvjtWzTLTUGIQisCBTkKZsoroGQuDkiiBTtJdNT8T_rZ6nqNQ6y-wsgZ6LMSCKJA_TC65jTJvu8903UoNzW2wnK7Z_Dt_oob9TYOOzNlkaa1YSQewmBhixV08wr8tmLOOzwtOxwCf5Ya-A'   -H 'Content-Type: application/json'   -d '{
   "serviceInstanceID":"1582510653894",
   "users":[
      {
         "display_name":"user1",
         "role":"MDC-Manager",
         "uid":"1000331001",
         "username":"user1"
      }
   ]
}'

In this example, the user user1 is granted MDC-Manager access to the sample-0 (1582510653894) instance.

After access has been granted to users, service instance tokens will be accepted by Master Data Connect.

Retrieving the platform token with the Cloud Pak for Data API

To retrieve the platform token by using the /icp4d-api/v1/authorize API, run the following curl command:

curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/icp4d-api/v1/authorize' -H 'Content-type: application/json' -d '{ "username": "<USER_NAME>", "password": "<PASSWORD" }'

Replace the following values in the curl command:

  • <CPD_CLUSTER_HOST>:<PORT> - your Cloud Pak for Data cluster host and port.
  • <USER_NAME> - your Cloud Pak for Data user name.
  • <PASSWORD> - your Cloud Pak for Data password.
curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/icp4d-api/v1/authorize' -H 'Content-type: application/json' -d '{ "username": "<USER_NAME>", "password": "<PASSWORD" }'

Retrieving the service instance ID with the Cloud Pak for Data API

To retrieve the service instance ID with the /zen-data/v3/service_instances API, run the following curl command:

curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v3/service_instances?add_on_type=mdc-app' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'

Replace the following values in the curl command:

  • <CPD_CLUSTER_HOST>:<PORT> - your Cloud Pak for Data cluster host and port.
  • <PLATFORM_TOKEN> - the user platform token.

This command produces the following JSON response:

{
   "limit":20,
   "offset":0,
   "service_instances":[
      {
         "addon_type":"mdc-app",
         "addon_version":"1.0.0",
         "created_at":"2020-05-10T22:15:55.557740Z",
         "description":"string",
         "display_name":"MDC1",
         "id":"1583878225057"
         ...
      }
   ],
   "total_count":1
}

The service instance ID will be returned in the id property of the response.

curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v3/service_instances?add_on_type=mdc-app' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'

The service instance ID will be returned in the id property of the response.

Obtaining the service instance token

After you have your service instance ID, you can obtain a service instance token in one of two ways:

  • With the Cloud Pak for Data web interface.
  • With the Cloud Pak for Data API.

Service instance tokens expire 20 minutes after creation.

Retrieving the service instance token with the Cloud Pak for Data web interface

To retrieve the service instance token by using the Cloud Pak for Data web interface:

  1. Log into the Cloud Pak for Data web interface.
  2. Navigate to My Instances, then select the appropriate Master Data Connect instance.
  3. Click View details.

The service instance token is displayed in the Access Information section.

Retrieving the service instance token with the Cloud Pak for Data API

To retrieve the service instance token by using the /zen-data/v2/serviceInstance/token API, run the following curl command:

curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v2/serviceInstance/token' -H 'Authorization: Bearer <PLATFORM_TOKEN> \
-d '{ 
   "serviceInstanceID": "<PROVISIONED_INSTANCE_ID>",
   "expiryTime:" <EXPIRY_TIME>
}'

Replace the following values in the curl command:

  • <CPD_CLUSTER_HOST>:<PORT> - your Cloud Pak for Data cluster host and port.
  • <PLATFORM_TOKEN> - the user platform token.
  • <PROVISIONED_INSTANCE_ID> - the instance ID of your provisioned instance.
  • <EXPIRY_TIME> - the token expiry time in minutes.

The expiryTime field is optional. If it is not provided, the default expiry time is 20 minutes.

This command produces the following the following JSON response:

{
   "AccessToken":"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b20iOnsiTW9kdWxlTmFtZSI6ImV6LWhlbG0tYXBwIiwiUm9sZSI6IkFkbWluIiwiU2VydmljZUluc3RhbmNlRGlzcGxheU5hbWUiOiJzYW1wbGUtMCIsIlNlcnZpY2VJbnN0YW5jZUlEIjoiMTU4MjUxMDY1Mzg5NCIsIlNlcnZpY2VJbnN0YW5jZVVzZXJOYW1lIjoiYWRtaW4iLCJaZW5EaXNwbGF5TmFtZSI6ImFkbWluIiwiWmVuVUlEIjoiMTAwMDMzMDk5OSIsIlplblVzZXJuYW1lIjoiYWRtaW4ifSwiZXhwIjoxNTgyNTE0NDQxLCJpYXQiOjE1ODI1MTMyNDEsImlzcyI6IklDUEQiLCJzdWIiOiJhZG1pbiIsInVpZCI6IjEwMDAzMzA5OTkifQ.FvtYQKkmIP5vguYGd7TVd-iD7Y4Z-KoTM1p-YlSCDzCzU7rnjogkOfF_0WCblUQQscliTzkV-YcjtfUxgXzObbKpu27oR1F85Z5PcBkMMhtVoxPw41Y9UeEpOy_2uYOr8aK8aJALHuG1W8VuOXoPI4oKh3cJM0M225xn0BK0_dTaVAioDVWiC8o0MDDn6uFDLEymM_U8JzZTFJbqzHUIlbmDphO4GbX28KduZvlrUVDzZ3hQPThUn-YnToLtYcKFWsdULWJHr4CCpPm5ZXGDAvjzTSonk8ktrMhHSgRV3loRhvtftXEZYfKQDGzhvAiKi7Ilv7OX85gJau_LgWv0iA",
   "TokenPayload":{
      "ModuleName":"mdc-app",
      "Role":"MDC-Manager",
      "ServiceInstanceDisplayName":"mdc-app-1",
      "ServiceInstanceID":"1582510653894",
      "ServiceInstanceUserName":"jsmith",
      "ZenDisplayName":"john smith",
      "ZenUID":"1000330999",
      "ZenUsername":"jsmith"
   }
}

The access token will be returned in the AccessToken property of the JSON response.

Access tokens are only valid for a particular instance of Master Data Connect.

curl -X POST 'https://<CPD_CLUSTER_HOST>:<PORT>/zen-data/v2/serviceInstance/token' -H 'Authorization: Bearer <PLATFORM_TOKEN> -d '{ 
   "serviceInstanceID": "<PROVISIONED_INSTANCE_ID>",
   "expiryTime:" <EXPIRY_TIME>
}'

Providing the service instance token to authorize the Master Data Connect API

You can pass the service instance token to authorize your Master Data Connect API calls in two ways:

  • Using the Authorize feature of the API Explorer user interface.
  • In the Authorization header of an API request.

Providing the service instance token with the Authorize feature of API Explorer

Navigate to the Swagger UI API Explorer by browsing to https://<CPD_CLUSTER_HOST>:<PORT>/api-cache/explorer

Replace the <CPD_CLUSTER_HOST>:<PORT> value in the above URL with your Cloud Pak for Data cluster host and port.

In the API Explorer, complete the following steps:

  1. Click Authorize at the top of the page
  2. Enter the instance token obtained from the Obtaining a service instance token section of this page.
  3. Click Authorize and then click Close.

The API Explorer passes your service instance token automatically for every API invoked from the API Explorer page.

Providing the service instance token in an Authorization header of an API request

To provide the service instance token in an Authorization header of an API request, run the following curl command:

curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/<API_PATH>' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'

Replace the following values in the curl command:

  • <CPD_CLUSTER_HOST>:<PORT> - your Cloud Pak for Data cluster host and port.
  • <API_PATH> - the path of your desired API (Such as /mdm/cache/v1/jobs).
  • <PLATFORM_TOKEN> - the user platform token.
curl -X GET 'https://<CPD_CLUSTER_HOST>:<PORT>/<API_PATH>' -H 'Authorization: Bearer <PLATFORM_TOKEN>' -H 'Content-type: application/json'

Methods

Get the liveness status of the system

GET /mdm/cache/v0/alive_status

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • The liveness check was successfully performed and the api is considered live and healthy.

  • Problem getting liveness status. An internal error occurred while attempting to determine the liveness status.

  • Liveness status is NOT LIVE.

No Sample Response

This method does not specify any sample responses.

Get the readiness status of the system

GET /mdm/cache/v0/ready_status

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • The readiness check was successfully performed and the api is considered ready to receive requests.

  • Problem getting readiness status. An internal error occurred while attempting to determine the readiness status.

  • Readiness status is NOT READY. The metadata store is not available.

No Sample Response

This method does not specify any sample responses.

Clear all data in the graph and persist the initial logical model

Requires the application role of 'Manager'. This method clears all data in the graph including vertexes, edges, and indexes. It then replaces the current model with the initial model.

POST /mdm/cache/v0/reset

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • The data reset job was started successfully.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem clearing data. An internal error occurred.

  • Problem clearing data. A reset job is already in progress.

No Sample Response

This method does not specify any sample responses.

Get the storage metadata

Requires the application role of 'Manager'.

GET /mdm/cache/v0/storage_metadata

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • The storage metadata has been successfully fetched.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem fetching storage metadata.

  • Problem fetching storage metadata. An internal error occurred while attempting to perform the operation.

No Sample Response

This method does not specify any sample responses.

Start an operation to bulk load data into the graph

Requires the application role of 'Writer'.

  • To run a sample bulk load, provide the type as 'sample' and the directory_ref identifying which sample data set to load. directory_path is not required when type is set to 'sample', if provided it will be ignored.
  • The available sample data sets are sample_contract_small, sample_consent_small, sample_contract, and sample_consent, these are the only acceptable values for 'directory_ref'
  • To run a dfs bulk load, provide the type as 'dfs' and the directory_path pointing to the location of the load data. 'directory_ref' is not required when type is set to 'dfs', if provided it will be ignored. Load data directories are expected to adhere to the following format:
record.properties
relationship.properties
record
--[record data files]
relationship
--[relationship data files]

The job id will be a random universally unique identifier, which is also appended to each job driver pod.

POST /mdm/cache/v0/bulk_load

Request

Valid JSON defining the data source and parameters for the bulk load job.

Response

Status Code

  • The bulk load job was successfully started.

  • Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem performing bulk load. An internal error occurred while attempting to perform the operation.

  • Problem performing bulk load. A bulk load process is already running.

No Sample Response

This method does not specify any sample responses.

Start an operation to perform a bulk update to the graph

Requires the application role of 'Manager'.

  • Performs all relationship deletions first, then record deletions.
  • After the deletions are completed, all record insertions/updates are performed next, followed by relationship insertions/updates.
  • Any element found in both deletions and insertions/updates is treated as a deletion, and is removed from the insertions/updates list before processing.
  • Any other case of a duplicated element will cause the update to fail.
  • If the ignore_redundant_updates flag is set to 'true', any update with a timestamp that is not newer than the existing timestamp for that element will not be applied, but it will not cause the bulk update transaction to fail. If the flag is set to 'false', invalid timestamps will cause failure.
  • A failed update will cause all changes performed by the bulk update transaction to be reverted back to the original graph state.
POST /mdm/cache/v0/bulk_update

Request

Query Parameters

  • Whether to ignore updates that fail due to missing or invalid 'record_last_updated' timestamps.

    Default: false

Valid JSON defining the elements to be inserted, updated or deleted on the graph.

Response

Status Code

  • The bulk update has been successfully processed.

  • Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem performing bulk update. An internal error occurred while attempting to update the graph.

No Sample Response

This method does not specify any sample responses.

Get information about the specified index

Requires the application role of 'Manager'.

GET /mdm/cache/v0/indices/{index_name}

Request

Path Parameters

  • The name of the graph index.

Response

Status Code

  • The reindex job status was retrieved successfully.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting index. The index was not found.

  • Problem getting index. An internal error occurred while attempting to retrieve index.

No Sample Response

This method does not specify any sample responses.

List the existing indices

Requires the application role of 'Manager'.

GET /mdm/cache/v0/indices

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • The indices have been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting indices. An internal error occurred while attempting to retrieve indices.

No Sample Response

This method does not specify any sample responses.

Fetch graph statistics

Requires the application role of 'Reader'.

POST /mdm/cache/v0/statistics

Request

No Request Parameters

This method does not accept any request parameters.

Response

Status Code

  • The graph statistics have been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting graph statistics. An internal error occurred while attempting to retrieve the graph statistics.

No Sample Response

This method does not specify any sample responses.

Get surrounding vertices and edges for a set of vertices

Requires the application role of 'Reader'.

  • Includes initial vertices in the result.
  • Returns a summary of graph elements. Does not include detailed information such as model attribute keys and values.
  • Ignores a vertex identifier if the vertex cannot be found. Returns an empty subgraph if no vertices are found.
  • Returns an edge in the resulting subgraph if its source vertex, target vertex and the edge itself can be reached within the specified number of hops from at least one initial vertex.
  • No more than 3 hops and 50 input vertices are permitted. The number of edges per vertex is capped at 50. Note that the number of edges per vertex may be less than this limit due to shared edges.
POST /mdm/cache/v0/subgraph

Request

Valid JSON defining scope parameters for the subgraph.

Response

Status Code

  • The subgraph has been successfully retrieved.

  • Problem retrieving subgraph. Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem retrieving subgraph. An internal error occurred while attempting to retrieve the subgraph.

No Sample Response

This method does not specify any sample responses.

Run a graph query

Requires the application role of 'Reader'. Apply domain object transformation to request model and from response model for integration with custom input and output data formats respectively.

POST /mdm/cache/v0/traverse

Request

Custom Headers

  • Allowable values: [application/json,application/xml,text/plain]

  • Allowable values: [application/json,application/xml,text/plain]

Query Parameters

  • The maximum number of elements to return in each page of results. The maximum limit is 50.

    Constraints: value ≤ 50

    Default: 10

  • The number of elements to skip before returning a page of results.

    Default: 0

Valid input defining the parameters on which to traverse the graph.

Response

Status Code

  • The graph query was executed successfully.

  • Problem executing graph query.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem executing graph query. An internal error occurred while executing the graph query.

No Sample Response

This method does not specify any sample responses.

Clean up job data

Requires the application role of 'Writer'.

POST /mdm/cache/v0/jobs/{job_id}/clean_up

Request

Path Parameters

  • The ID of the job.

Response

Status Code

  • The job clean up was successful.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem cleaning up job. Job not found.

  • Problem cleaning up job. Jobs of this type are not supported.

  • Problem cleaning up job. The job data could not be found.

  • Problem cleaning up job. An internal error occurred while cleaning up the job.

  • Problem cleaning up job. Operation cannot be performed while job is still running.

No Sample Response

This method does not specify any sample responses.

Stop a given job

Requires the application role of 'Writer'. Stops a job if it is currently running. This does not rollback changes made by the job process prior to stopping the job. Full deletion of job resources may take up to a few minutes.

POST /mdm/cache/v0/jobs/{job_id}/stop

Request

Path Parameters

  • The ID of the job.

Response

Status Code

  • The job was stopped successfully.

  • Problem stopping job process. The process with job id <job_id> is not running.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem stopping job process. A process with job id <job_id> could not be found.

  • Problem stopping job process. Jobs of this type are not supported.

  • Problem stopping job process. An internal error occurred while attempting to perform the operation.

No Sample Response

This method does not specify any sample responses.

List all jobs

Requires the application role of 'Reader'. Includes optional filters on job type and status.

GET /mdm/cache/v0/jobs

Request

Query Parameters

  • The number of jobs to skip before returning a page of results.

    Default: 0

  • The maximum number of jobs to return in each page of results. The maximum limit is 50.

    Constraints: value ≤ 50

    Default: 10

  • Filter by job status.

    Allowable values: [not_started,prep,queued,running,succeeded,failed,canceled]

  • Filter by job type.

    Allowable values: [bulk_load,model_update,reset]

Response

Status Code

  • The list of jobs was retrieved successfully.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting list of jobs. An internal error occurred while attempting to retrieve the list of jobs.

No Sample Response

This method does not specify any sample responses.

Get information for a given job

Requires the application role of 'Reader'.

GET /mdm/cache/v0/jobs/{job_id}

Request

Path Parameters

  • The ID of the job.

Response

Status Code

  • The job status was retrieved successfully.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting job information. Job not found.

  • Problem getting job information. An internal error occurred while attempting to retrieve the job information.

No Sample Response

This method does not specify any sample responses.

Get the current Logical Model

Requires the application role of 'Reader'.

GET /mdm/cache/v0/model

Request

Query Parameters

  • Whether to return localized labels and exclude the label translations.

    Default: false

Response

Status Code

  • The Logical Model has been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting the Logical Model. An internal error occurred.

No Sample Response

This method does not specify any sample responses.

Update the Logical Model

Requires the application role of 'Manager'. The proposed updated model must be a superset of the preexisting model. In the case of duplicate locale keys, only the last occurrence of a locale element with the duplicate key is used.

POST /mdm/cache/v0/model

Request

Valid JSON defining the logical model with updates. Must be a superset of the existing model.

Response

Status Code

  • The Logical Model update was started successfully.

  • Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem updating Logical Model. The Logical Model does not exist.

  • Problem updating Logical Model. An internal error occurred while attempting to update the Logical Model.

  • Problem updating Logical Model. Another update of the Logical Model is in progress.

No Sample Response

This method does not specify any sample responses.

Get a single record

Requires the application role of 'Reader'.

GET /mdm/cache/v0/records/{id}

Request

Path Parameters

  • The ID of the record.

Query Parameters

  • The list of record attributes to include in the results.

    Constraints: contains only unique items

  • The list of record attributes to exclude in the results.

    Constraints: contains only unique items

Response

Status Code

  • The record has been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting record: Record does not exist.

  • Problem getting record. An internal error occurred while attempting to retrieve the record.

No Sample Response

This method does not specify any sample responses.

List all records

Requires the application role of 'Reader'.

GET /mdm/cache/v0/records

Request

Query Parameters

  • The number of records to skip over. The maximum offset is 10000.

    Constraints: value ≤ 10000

    Default: 0

  • The number of records to be returned. The maximum limit is 50.

    Constraints: value ≤ 50

    Default: 10

Response

Status Code

  • The records have been successfully retrieved.

  • Problem getting records. Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting records. An internal error occurred while attempting to retrieve the records.

No Sample Response

This method does not specify any sample responses.

Retrieve a subgraph of the neighboring vertices and associated edges for a given record

Requires the application role of 'Reader'.

POST /mdm/cache/v0/records/{id}/neighbors

Request

Path Parameters

  • The ID of the record.

Valid JSON defining the request, including attributes filter, limit, and offset.

Response

Status Code

  • The subgraph of neighbors has been successfully retrieved.

  • Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem retrieving neighbors. Record does not exist.

  • Problem retrieving neighbors. An internal error occurred while attempting to retrieve the subgraph of neighbors.

No Sample Response

This method does not specify any sample responses.

List the relationships for a single given record

Requires the application role of 'Reader'.

GET /mdm/cache/v0/records/{id}/relationships

Request

Path Parameters

  • The ID of the record.

Response

Status Code

  • The relationships have been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem retrieving relationships. Record not found

  • Problem retrieving relationships. An internal error occurred.

No Sample Response

This method does not specify any sample responses.

Get a single given relationship for a given record

Requires the application role of 'Reader'.

GET /mdm/cache/v0/records/{id}/relationships/{relationship_id}

Request

Path Parameters

  • The ID of the record.

  • The ID of the linked relationship to return.

Response

Status Code

  • The relationship has been successfully retrieved.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting relationship. Relationship does not exist.

  • Problem getting relationship. An internal error occurred while attempting to retrieve the relationship.

No Sample Response

This method does not specify any sample responses.

Run a full text or property query search

Requires the application role of 'Reader'. Search type is configurable in the message body, as well as the search terms and filters. Pagination is supported.

POST /mdm/cache/v0/search

Request

Custom Headers

  • Allowable values: [application/json,application/xml,text/plain]

  • Allowable values: [application/json,application/xml,text/plain]

Query Parameters

  • The type of results to return from the search.

    Allowable values: [stats,results]

    Default: results

  • The maximum number of elements to return in each page of results. The maximum limit is 50.

    Constraints: value ≤ 50

    Default: 10

  • The number of elements to skip before returning a page of results.

    Default: 0

  • The list of record attributes to include in the results.

    Constraints: contains only unique items

  • The list of record attributes to exclude in the results.

    Constraints: contains only unique items

Valid input defining the search criteria.

Response

Status Code

  • The search was performed successfully.

  • Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Request timed out.

  • Problem searching. An internal error occurred while attempting to perform the search.

No Sample Response

This method does not specify any sample responses.

List the defined graph query templates

Requires the application role of 'Reader'. Apply domain object transformation to request model and from response model for integration with custom input and output data formats respectively.

GET /mdm/cache/v0/traversal_templates

Request

Custom Headers

  • Allowable values: [application/json,application/xml,text/plain]

Response

The wrapper object for a list of traversal templates.

Status Code

  • The graph query templates were retrieved successfully.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting list of query templates. An internal error occurred while retrieving the list of query templates.

No Sample Response

This method does not specify any sample responses.

Create a new traversal template

Requires the application role of 'Manager'. Apply Domain Object Transformation on the response model for integration with custom output data formats.

POST /mdm/cache/v0/traversal_templates

Request

Custom Headers

  • Allowable values: [application/json,application/xml,text/plain]

  • Allowable values: [application/json,application/xml,text/plain]

The definiton of the graph query template.

Response

Status Code

  • The query template was defined successfully.

  • Input validation failed.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem defining query template. An internal error occurred while defining the query template.

No Sample Response

This method does not specify any sample responses.

Get a defined graph query template

Requires the application role of 'Reader'. Apply Domain Object Transformation on the response model for integration with custom output data formats.

GET /mdm/cache/v0/traversal_templates/{id}

Request

Custom Headers

  • Allowable values: [application/json,application/xml,text/plain]

Path Parameters

  • The ID of the graph query template.

Response

Status Code

  • The graph query template was retrieved successfully.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem getting query template. The query template could not be found.

  • Problem getting query template. An internal error occurred while retrieving the query template.

No Sample Response

This method does not specify any sample responses.

Delete a defined graph query template

Requires the application role of 'Manager'.

DELETE /mdm/cache/v0/traversal_templates/{id}

Request

Path Parameters

  • The ID of the graph query template.

Response

Status Code

  • The graph query template was deleted successfully.

  • Problem processing request. The user is not authenticated.

  • Problem processing request. The user is not authorized to perform the request.

  • Problem deleting query template. The query template could not be found.

  • Problem deleting query template. An internal error occurred while deleting the query template.

No Sample Response

This method does not specify any sample responses.