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:
- Log into the Cloud Pak for Data web interface.
- Navigate to My Instances, then select the specified instance.
- Click the Manage access option.
- 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.
- 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
, orMDC-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:
- Log into the Cloud Pak for Data web interface.
- Navigate to My Instances, then select the appropriate Master Data Connect instance.
- 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:
- Click Authorize at the top of the page
- Enter the instance token obtained from the Obtaining a service instance token section of this page.
- 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
Request
No 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
Request
No 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
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
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
Get the storage metadata
Requires the application role of 'Manager'.
GET /mdm/cache/v0/storage_metadata
Request
No Request Parameters
Response
Possible values: [
minikube
,k8s
,cloud
,cp4d
]
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
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.
Allowable values: [
dfs
,sample
]Allowable values: [
sample_contract_small
,sample_consent_small
,sample_contract
,sample_consent
]
data_source
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
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.
upserts
deletions
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
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
supplemental information about the index
metadata
Possible values: [
mixed
,composite
]Possible values: [
no_info
,prep
,queued
,running
,succeeded
,failed
]
reindex_information
index
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
Request
No 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
Request
No Request Parameters
Response
aggregate_counts
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
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.
Constraints: 0 ≤ value ≤ 3
Default:
0
Constraints: contains only unique items
include
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
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
first
last
previous
next
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
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
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
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
first
last
previous
next
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
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
Possible values: [
not_started
,prep
,queued
,running
,succeeded
,failed
,canceled
]Possible values: [
upload
,match
,delete
,data_delete
,export
,search
,stats
,reindex
,event_processing
,bulk_load
,sync
,cloudant_changes
,model_update
,reset
]
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
Request
Query Parameters
Whether to return localized labels and exclude the label translations.
Default:
false
Response
current Logical Model
model
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
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
Possible values: [
not_started
,prep
,queued
,running
,succeeded
,failed
,canceled
]Possible values: [
upload
,match
,delete
,data_delete
,export
,search
,stats
,reindex
,event_processing
,bulk_load
,sync
,cloudant_changes
,model_update
,reset
]
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
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
attributes
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
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
first
last
previous
next
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
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.
Example:
[]
Example:
10
Response
attributes
source_record
Example:
10
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
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
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
metadata
attributes
relationship
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
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.
Search type of 'ENTITY' is not supported.
Allowable values: [
record
,entity
]Allowable values: [
and
,or
]
query
Response
first
last
previous
next
stats
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
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.
A query template that can be used in running graph traversals.
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
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.
- Use the placeholder
g
to represent the GraphTraversalSource object. Declare any other variables used in the query template as placeholders. - Ensure that the result of the query is a GraphTraversal object to ensure that the query runs successfully.
- Use the placeholder
Response
metadata
A query template that can be used in running graph traversals.
- Use the placeholder
g
to represent the GraphTraversalSource object. Declare any other variables used in the query template as placeholders. - Ensure that the result of the query is a GraphTraversal object to ensure that the query runs successfully.
- Use the placeholder
template
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
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
metadata
A query template that can be used in running graph traversals.
- Use the placeholder
g
to represent the GraphTraversalSource object. Declare any other variables used in the query template as placeholders. - Ensure that the result of the query is a GraphTraversal object to ensure that the query runs successfully.
- Use the placeholder
template
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
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.