Skip to main contentlogoCreated with Sketch.
  • Start for free

    • Introduction

    Last updated: 2020-06-18

    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:

    1. Grant users access to Master Data Connect.
    2. Retrieve the platform token.
    3. Retrieve the service instances associated with the platform token.
    4. Obtain a service instance token by providing your service instance ID.
    5. Use the service instance token to authorize your Master Data Connect API calls.

    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

    Response Body

    SystemLiveness

    Status Code

    • 200

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

    • 500

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

    • 503

      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

    Response Body

    SystemReadiness

    Status Code

    • 200

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

    • 500

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

    • 503

      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

    • 202

      The data reset job was started successfully.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 500

      Problem clearing data. An internal error occurred.

    • 503

      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

    Response Body

    One of

    Status Code

    • 200

      The storage metadata has been successfully fetched.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 405

      Problem fetching storage metadata.

    • 500

      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

    Request Body

    BulkLoadRequest

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

    Response

    Status Code

    • 202

      The bulk load job was successfully started.

    • 400

      Input validation failed.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 500

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

    • 503

      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

    • ignore_redundant_updates
      boolean

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

      Default: false

    Request Body

    SyncUpdateRequest

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

    Response

    Status Code

    • 204

      The bulk update has been successfully processed.

    • 400

      Input validation failed.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 500

      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

    • index_name
      string

      The name of the graph index.

    Response

    Response Body

    IndexWrapper

    Status Code

    • 200

      The reindex job status was retrieved successfully.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 404

      Problem getting index. The index was not found.

    • 500

      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

    Response Body

    IndicesResponseWrapper

    Status Code

    • 200

      The indices have been successfully retrieved.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 500

      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

    Response Body

    StatisticsResult

    Status Code

    • 200

      The graph statistics have been successfully retrieved.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 500

      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

    Request Body

    SubgraphParameters

    Valid JSON defining scope parameters for the subgraph.

    Response

    Response Body

    Subgraph

    Status Code

    • 200

      The subgraph has been successfully retrieved.

    • 400

      Problem retrieving subgraph. Input validation failed.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 500

      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

    • Accept
      string

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

    • Content-Type
      string

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

    Query Parameters

    • limit
      integer

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

      Constraints: value ≤ 50

      Default: 10

    • offset
      integer

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

      Default: 0

    Request Body

    GraphQueryParameters

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

    Response

    Response Body

    TraversalResult

    Status Code

    • 200

      The graph query was executed successfully.

    • 400

      Problem executing graph query.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 500

      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

    • job_id
      string

      The ID of the job.

    Response

    Status Code

    • 204

      The job clean up was successful.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 404

      Problem cleaning up job. Job not found.

    • 405

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

    • 410

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

    • 500

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

    • 503

      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

    • job_id
      string

      The ID of the job.

    Response

    Status Code

    • 200

      The job was stopped successfully.

    • 400

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

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 404

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

    • 405

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

    • 500

      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

    • offset
      integer

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

      Default: 0

    • limit
      integer

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

      Constraints: value ≤ 50

      Default: 10

    • status
      string

      Filter by job status.

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

    • type
      string

      Filter by job type.

      Allowable values: [bulk_load,model_update,reset]

    Response

    Response Body

    JobsResponse

    Status Code

    • 200

      The list of jobs was retrieved successfully.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 500

      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

    • job_id
      string

      The ID of the job.

    Response

    Response Body

    JobResponse

    Status Code

    • 200

      The job status was retrieved successfully.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 404

      Problem getting job information. Job not found.

    • 500

      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

    • localize
      boolean

      Whether to return localized labels and exclude the label translations.

      Default: false

    Response

    Response Body

    LogicalModelResponse

    Status Code

    • 200

      The Logical Model has been successfully retrieved.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 500

      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

    Request Body

    LogicalModelRequest

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

    Response

    Response Body

    JobResponse

    Status Code

    • 202

      The Logical Model update was started successfully.

    • 400

      Input validation failed.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 404

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

    • 500

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

    • 503

      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

    • id
      int64

      The ID of the record.

    Query Parameters

    • include
      string[]

      The list of record attributes to include in the results.

      Constraints: contains only unique items

    • exclude
      string[]

      The list of record attributes to exclude in the results.

      Constraints: contains only unique items

    Response

    Response Body

    Record

    Status Code

    • 200

      The record has been successfully retrieved.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 404

      Problem getting record: Record does not exist.

    • 500

      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

    • offset
      integer

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

      Constraints: value ≤ 10000

      Default: 0

    • limit
      integer

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

      Constraints: value ≤ 50

      Default: 10

    Response

    Response Body

    Records

    Status Code

    • 200

      The records have been successfully retrieved.

    • 400

      Problem getting records. Input validation failed.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 500

      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

    • id
      int64

      The ID of the record.

    Request Body

    NeighborSubgraphParameters

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

    Response

    Response Body

    NeighborsResponse

    Status Code

    • 200

      The subgraph of neighbors has been successfully retrieved.

    • 400

      Input validation failed.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 404

      Problem retrieving neighbors. Record does not exist.

    • 500

      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

    • id
      int64

      The ID of the record.

    Response

    Response Body

    Relationships

    Status Code

    • 200

      The relationships have been successfully retrieved.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 404

      Problem retrieving relationships. Record not found

    • 500

      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

    • id
      int64

      The ID of the record.

    • relationship_id
      string

      The ID of the linked relationship to return.

    Response

    Response Body

    JsonRelationshipResponse

    Status Code

    • 200

      The relationship has been successfully retrieved.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 404

      Problem getting relationship. Relationship does not exist.

    • 500

      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

    • Accept
      string

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

    • Content-Type
      string

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

    Query Parameters

    • return_type
      string

      The type of results to return from the search.

      Allowable values: [stats,results]

      Default: results

    • limit
      integer

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

      Constraints: value ≤ 50

      Default: 10

    • offset
      integer

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

      Default: 0

    • include
      string[]

      The list of record attributes to include in the results.

      Constraints: contains only unique items

    • exclude
      string[]

      The list of record attributes to exclude in the results.

      Constraints: contains only unique items

    Request Body

    Criteria

    Valid input defining the search criteria.

    Response

    Response Body

    SearchResult

    Status Code

    • 200

      The search was performed successfully.

    • 400

      Input validation failed.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 408

      Request timed out.

    • 500

      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

    • Accept
      string

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

    Response

    Response Body

    TraversalTemplateList

    The wrapper object for a list of traversal templates.

    Status Code

    • 200

      The graph query templates were retrieved successfully.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 500

      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

    • Accept
      string

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

    • Content-Type
      string

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

    Request Body

    TraversalTemplateParameters

    The definiton of the graph query template.

    Response

    Response Body

    TraversalTemplateWrapper

    Status Code

    • 200

      The query template was defined successfully.

    • 400

      Input validation failed.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 500

      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

    • Accept
      string

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

    Path Parameters

    • id
      string

      The ID of the graph query template.

    Response

    Response Body

    TraversalTemplateWrapper

    Status Code

    • 200

      The graph query template was retrieved successfully.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 404

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

    • 500

      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

    • id
      string

      The ID of the graph query template.

    Response

    Status Code

    • 204

      The graph query template was deleted successfully.

    • 401

      Problem processing request. The user is not authenticated.

    • 403

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

    • 404

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

    • 500

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

    No Sample Response

    This method does not specify any sample responses.