REST API
The REST API provides the ability to browse data, statuses, and parameters maintained by MDM via REST interfaces. The API supports REST Maturity Level 2.
By default, the REST API uses the default server port (8051
) set in MDM Server Application Properties.
The path to REST API is /api/rest
and it cannot be configured.
The REST API only uses basic HTTP authentication.
However, you can configure a more secure authentication method, see MDM Server Application Properties, API Endpoint Required Role Configuration section.
The following sections describe the uses of the REST API.
Requests that reference values containing reserved characters need to be written using URL-encoding (for example, Please note that the comma character ( |
OpenAPI Swagger
The Swagger UI allows you to see a list of available REST API endpoints and operations in a browser-based HTML interface.
http://localhost:8051/swagger-ui.html
Specification is available at `http://localhost:8051/v3/api-docs`. The Swagger is using the |
Listing REST Endpoints
A response contains a directory of exposed services and interfaces and additional information, including the RW mode.
http://localhost:8051/api/rest/
Response
{
"name" : "REST API",
"version" : "1.0",
"rwmode" : "RW",
"uris" : {
"tasks" : "http://localhost:8051/api/rest/tasks",
"eventHandlers" : "http://localhost:8051/api/rest/event-handlers",
"instance" : "http://localhost:8051/api/rest/instance",
"master" : "http://localhost:8051/api/rest/master",
"parameters" : "http://localhost:8051/api/rest/parameters",
"sourceSystems" : "http://localhost:8051/api/rest/source-systems",
"statistics" : {
"instance" : "http://localhost:8051/api/rest/statistics/instance",
"master" : "http://localhost:8051/api/rest/statistics/master"
},
"interfaces" : {
"services" : "http://localhost:8051/api/rest/interfaces/services",
"exports" : "http://localhost:8051/api/rest/interfaces/batch/exports",
"loads" : "http://localhost:8051/api/rest/interfaces/batch/loads",
"consumers" : "http://localhost:8051/api/rest/interfaces/streaming/consumers"
}
}
}
Reading Records
A GET request is used to access instance and master layer information, entity information, records or a single record.
Instance Layer
Endpoint | Description |
---|---|
/instance |
Returns a list of entities on the instance layer. |
/instance/{entity} |
Returns all the records of the selected instance entity. |
/instance/{entity}/metadata |
Returns the metadata of the selected instance entity: columns, relationships, and ways to access a particular record. |
/instance/{entity}/{id} |
Returns an instance record by its |
/instance/{entity}/{origin}/{sourceId} |
Returns an instance record by its |
Master Views
Endpoint | Description |
---|---|
/master |
Returns a list of master views. |
/master/{view} |
Returns a list of entities on the selected master view. |
/master/{view}/{entity} |
Returns all the records of the selected master view. |
/master/{view}/{entity}/metadata |
Returns the metadata of the selected master entity: columns and ways to access a particular record. |
/master/{view}/{entity}/{id} |
Returns a master record by its |
/master/{view}/{entity}/{origin}/{sourceID} |
Returns a master record by the |
If {origin} contains a # and is used in the URI, it must be escaped with %23 .
|
Parameters
Results and their presentation can be customized with the following parameters:
Parameter | Description |
---|---|
columns |
Comma-separated list of columns that should be returned (by default all columns are returned). |
offset |
Used for paging. Offsets the first returned record, starts at 0. |
page |
Used for paging. Alternative to offset - returns nth page, that is, offset=page*count, starts at 0. |
count |
When used alone or with |
sort |
Name of column to sort records by, optionally suffixed with |
<column_name>=<value> |
Filters by the exact value of the column with wildcard support; multiple values of one column are supported: separate them by a comma. |
preload=<relationship1>,<relationship2> |
Lists related records according to the provided relationships. |
GET /instance/{entity}?offset=2&count=5
GET /instance/{entity}?columns=src_first_name,src_sin&src_first_name=Joh*&sort=std_birth_date:DESC
GET /master/{view}/{entity}?offset=2&count=5
GET /master/{view}/{entity}?columns=cmo_first_name,cmo_sin&cmo_first_name=Joh*&sort=cmo_birthdate:DESC
GET /instance/{entity}?preload=contacts,addresses
// advanced preload examples
GET /master/masters/party/1020?preload=addresses.instances,contacts
GET /master/masters/party/1020?preload=addresses(cmo_type=Residential,cmo_state=US)
Sample GET Requests and Responses
Request on the Instance Layer
GET /instance/party/1007
Response
{
"type": "party",
"metadata":
{
"id": 1007,
"origin": "crm#customer#party",
"sourceSystem": "crm",
"active": true,
"sourceTimestamp": "2015-07-23T14:14:04Z",
"creationDate": "2017-09-08T15:39:59Z",
"lastUpdateDate": "2017-09-08T15:40:03Z",
"lastSourceUpdateDate": "2017-09-08T15:40:03Z",
"activationDate": "2017-09-08T15:39:59Z",
"creationTid": 1002,
"lastUpdateTid": 2814,
"lastSourceUpdateTid": 2814,
"activationTid": 1002
},
"attributes":
{
"source_id": "1001",
"master_id": 1238,
"propose_id": 1273,
"src_first_name": "DR. JOHN",
...
},
...
}
Request on a Master View
GET /master/masters/party/1235
Response
{
"type": "party",
"metadata": {
"id": 1235,
"active": true,
"creationDate": "2017-09-08T15:39:59Z",
"lastUpdateDate": "2017-09-08T15:39:59Z",
"activationDate": "2017-09-08T15:39:59Z",
"creationTid": 1002,
"lastUpdateTid": 1002,
"activationTid": 1002
},
"attributes": {
"cmo_type": "P",
"cmo_first_name": "John",
...
}
}
Identify
The 'Identify' service answers the question, "is this record similar to any record stored in the hub?". Input is in the form of the instance entity, while similarity is defined by the matching rules of this entity. Output is either matching information and master record or nothing.
The service accepts POST requests at endpoint /master/{view}/{entity}/identify
with the following structure:
Identify request
POST /master/masters/party/identify
{
"sourceSystem" : "life",
"record" : {
"attributes" : {
"src_first_name" : "Anto",
"src_last_name" : "Lese",
"src_sin" : "387958572"
},
"relationships" : [{
"contacts" : [{
"attributes": {
"src_type" : "PHONE",
"src_value" : "416-206-1234"
}
},
{
"attributes": {
"src_type" : "EMAIL",
"src_value" : "alese@aol.com"
}
}]
}]
}
}
As an input, the service gets:
-
one record of the instance entity - attributes of origin
SOURCE
-
(optional) records of related entities - attributes of origin
SOURCE
The service cleanses input data and tries to match the record to records in the hub using matching rules. If the input record is matched to a master group, a master record is returned. For example, the response if the record is matched is:
Identify Response
{
"matchMetadata" : {
"matchRelatedId" : 1007,
"matchQuality" : 0.0,
"matchRuleName" : "name+sin"
},
"record" : {
"type" : "party",
"metadata" : {
"id" : 1030
// more metadata
},
"attributes" : {
"cmo_name" : "John",
// more attributes
}
}
}
If matching has proposals enabled, proposals are returned as well. It is possible to have only proposals in response (record matches only using proposal rules).
Identify Response
{
"matchMetadata" : { /* ... */ },
"record" : { /* ... */ },
"proposals" : [ {
"matchMetadata" : {
"matchRelatedId" : 1007,
"matchQuality" : 0.0,
"matchRuleName" : "name+sin"
},
"record" : {
"type" : "party",
"metadata" : {
"id" : 1030
// more metadata
},
"attributes" : {
"cmo_name" : "John",
// more attributes
}
}
},
// more proposals
]
}
If there are too many proposals (more than the runtime parameter nme.services.range.maxCount
, default 100), proposals are returned in a short format:
Identify Response
{
"matchMetadata" : { /* filled */ },
"record" : { /* */ },
"proposals" : [ {
"masterId" : 1012,
"matchRelatedId" : 1007,
"matchQuality" : 0.0,
"matchRuleName" : "name+sin"
}
// more proposals
]
}
Search
This services allows you to search for records by attributes and values using a POST request.
For example, the following request searches for records with src_name
values John
or Paul
and a std_Age
value 42
:
Search request
POST /instance/party/search
{
"src_name" : ["John","Paul"],
"std_age" : 42
}
The request supports the following parameters:
Parameter | Description |
---|---|
offset |
Used for paging. Offsets the first returned record, starts at 0. |
count |
When used alone or with |
Reading Historical Records
It is possible to get historical values of a record with a GET request.
Endpoint | Description |
---|---|
/history |
Returns the list of all historized entities. |
/instance/{entity}/history/metadata |
Returns the list of columns stored in the historized instance entity as configured in |
/instance/{entity}/{id}/history |
Returns historical instance records by the record id. /instance/{entity}/{origin}/{source_id}/history |
Returns historical instance records by origin and the record id. |
/master/{view}/{entity}/{id}/history |
Returns historical master records by the record id. |
/master/{view}/{entity}/history/metadata |
Setting the Timeframe
It is possible to limit the number of results by specifying the from
, to
, or at
parameters in the request.
The from
and to
parameters can be combined or used separately.
History Request
/master/masters/party/1734/history?from=2017-08-16T11:15:55Z&to=2017-08-25T11:15:55Z
History Response
[ {
"type" : "partymasters",
"metadata" : {
"id" : 1734,
"validFrom" : "2017-08-21T14:47:02Z",
"validTo" : "2017-08-24T14:48:11Z",
"active" : true
},
"attributes" : {
"cmo_type" : "P",
"cmo_first_name" : "John",
"cmo_last_name" : "Smith",
"cmo_gender" : "M",
"cmo_birth_date" : "1978-11-16T00:00:00Z",
"cmo_sin" : "95242433",
"dq_indicator" : 100000,
"dq_indicator_name" : "medium",
"group_size" : 2,
"published_by" : "admin"
}
}, {
"type" : "partymasters",
"metadata" : {
"id" : 1734,
"validFrom" : "2017-08-16T14:37:15Z",
"validTo" : "2017-08-21T14:47:02Z",
"active" : true
},
"attributes" : {
"cmo_type" : "P",
"cmo_first_name" : "J",
"cmo_last_name" : "Smith",
"cmo_birth_date" : "1978-11-16T00:00:00Z",
"cmo_sin" : "95242433",
"dq_indicator" : 111003,
"dq_indicator_name" : "medium",
"group_size" : 1,
"published_by" : "multiload"
}
} ]
Modifying Records
Mapping of HTTP methods to change type is as usual in REST:
-
Insert via POST
-
Update via PUT
-
Deactivation via DELETE
However MDM can automatically adjust between create and update depending on whether the record is present in the MDM repository, that is, an attempt to update (PUT) a non-existing record is automatically changed to an insert operation (POST), and vice versa.
Record Identification in Requests
Records are identified by their id or a combination of origin and source_id (for instance records only). This identification can be sent in the URI or in the request body.
Record ID Sent in the Request URI
PUT /instance/{entity}/{id}
POST /instance/{entity}/{origin}/{sourceId}
PUT/POST /api/rest/master/{entity}/{id}
If {origin} contains a # and is used in the URI, it must be escaped with %23 .
|
Record ID Sent in the Request Body
POST /instance/{entity}
{
"origin" : "crm#customer#party",
"source_id" : "cdr48"
}
All combinations of POST/PUT/DELETE and identification are supported to provide maximum integration flexibility.
The only forbidden variant is sending id
when creating a new record (MDM generates its own ids).
POST Request Example
Instance Layer
Insert via a POST Request
POST /instance/party
{
"origin" : "crm#customer#party",
"source_id" : "cdr48",
"source_timestamp" : "2015-07-23T14:14:04Z",
"attributes" : {
"src_first_name" : "Johny",
"src_sin" : "547-954-624"
}
}
Response
{
"result": "ok",
"records": {
"entity": {
"id": 4051,
"origin": "crm#customer#party",
"source_id": "cdr48-ase",
"action": "INSERT"
}
}
}
Insert with relationships via a POST Request
{
"origin" : "PAS#policyrole#party",
"source_id" : "6776",
"source_timestamp" : "2019-03-27T00:00:00Z",
"attributes" : {
"src_name_first" : "LINDA",
"src_name_last" : "CORRIE",
"src_name_middle" : "",
"src_gender" : "Female",
"src_date_of_birth" : ""
},
"relationships": {
"contact": [{
"source_id":"670",
"origin":"PAS#policyrole#contact",
"attributes": {
"party_source_id" : "671",
"src_value": "5354856",
"src_type" : "Home Phone"
}
}
]
}
}
When inserting a record with relationships via a POST request, you will need to modify Parent Role / Child Role in the MDM Logical Model according to what is defined in your request.
Alternatively, if you have no Parent or Child Role defined in the model, use rev_party_has_contact in place of contact in the request.
|
Master Layer
Insert via a POST request
POST http://localhost:8051/api/rest/master/masters/party
{
"attributes": {
"cmo_first_name": "rest3",
"cmo_sin": "12345"
},
"relationships": {
"addresses": [{
"attributes":{
"cmo_street": "ab1",
"cmo_city": "cd1"
}
},
{
"attributes":{
"cmo_street": "ab2",
"cmo_city": "cd2"
}
}]
}
}
Response
{
"result": "ok",
"records": {
"id": 302003,
"recordChange": "INSERT",
"relationships": {
"addresses": [
{
"id": 302004,
"recordChange": "INSERT"
},
{
"id": 302005,
"recordChange": "INSERT"
}
]
}
}
}
PUT Request Example
Instance Layer
Update via a PUT Request
PUT /instance/party/crm%23customer%23party/1001
{
"source_timestamp" : "2015-07-23T14:14:04Z",
"attributes": {
"src_first_name": "Dr. John",
"src_sin": "764-785-685"
},
"relationships": {
"id_documents": [{
"source_id":"pass-94515",
"origin":"crm#customer#id_document",
"attributes": {
"src_type" : "passport",
"src_value" : "489465498",
"party_source_id" : "1001"
}
}]
}
}
The central entity was updated, related entities were ignored since the data in the request was the same as before.
Response
{
"result": "ok",
"records": {
"entity": {
"action": "UPDATED",
"id": 17603215,
"origin": "crm#customer#party",
"source_id": "12121212"
},
"relationships": {
"id_documents": {
"entity": {
"action": "NONE",
"id": 2207,
"origin": "crm#customer#id_document",
"source_id": "100_id_card_1"
}
}
}
}
}
DELETE Request Example
Instance Layer
Record Deactivation via a DELETE Request
DELETE http://localhost:8051/api/rest/instance/party/17603215
<empty-body>
Response
{
"result": "ok",
"records": {
"entity": {
"id": 20003264,
"origin": "crm#customer#id_document",
"source_id": "100_id_card_1666"
"action": "DEACTIVATED",
}
}
}
Master Layer
It is only possible to delete authored master records via the API. The DELETE request for these records causes an actual delete rather than a record deactivation (logical delete). For more information see Batch Interface, section Deletion Strategy. |
Record Deletion via a DELETE Request
DELETE http://localhost:8051/api/rest/master/masters/party/302003
<empty-body>
Response
{
"result": "ok",
"records": {
"id": 302003,
"recordChange": "DELETE"
}
}
Override Interfaces
Instance Records
Requests on the instance layer use the following parameters for record identification.
Parameter | Description |
---|---|
|
Instance table name as defined in the model. |
|
ID of the record. |
You can use attributeName
either in the URI or in the request body to specify one or more attributes involved in the request.
Listing Record Overrides
Use the following request to get the original value of the attribute before an override has been set. The request body is empty.
Request
GET /instance/{entity}/{id}/override/{attributeName}
Response
{
"recordType": "instance",
"entityType": "party",
"recordId": 1982,
"overrides": [
{
"attributeName": "src_first_name",
"value": "John"
}
]
}
Use the following request to get the list of all attributes with overrides and their values before the override has been set. The request body is empty.
Request
GET /instance/{entity}/{id}/override
Response
{
"recordType": "instance",
"entityType": "party",
"recordId": 1982,
"overrides": [
{
"attributeName": "src_first_name",
"value": "John"
},
{
"attributeName": "src_last_name",
"value": "Smith"
}
]
}
Setting Overrides
Use the following request to set an override on a particular attribute.
Specify value
in the request body.
The response is empty.
Request
PUT /instance/{entity}/{id}/override/{attributeName}
{"value": "John"}
Use the following request to set overrides on several attributes.
Specify both the attributeName
and value
in the request body.
The response is empty.
Request
PUT /instance/{entity}/{id}/override
{
"overrides": [
{
"attributeName": "src_first_name",
"value": "John"
},
{
"attributeName": "src_last_name",
"value": "Smith"
}
]
}
Deleting Overrides
Use the following request to delete an override on a particular attribute. Both the request and response body are empty.
Request
DELETE /instance/{entity}/{id}/override/{attributeName}
Use the following request to delete all overrides currently set on a record. Both the request and response body are empty.
Request
DELETE /instance/{entity}/{id}/override
Master Records
Requests on the master layer use the following parameters for record identification.
Parameter | Description |
---|---|
|
Name of the master layer/view |
|
Instance table name as defined in the model. |
|
ID of the record. |
You can use attributeName
either in the URI or in the request body to specify one or more attributes involved in the request.
Listing Record Overrides
Use the following request to get the original value of the attribute before an override has been set. The request body is empty.
Request
GET /master/{viewName}/{entity}/{id}/override/{attributeName}
Response
{
"recordType": "master",
"entityType": "party",
"recordId": 1982,
"overrides": [
{
"attributeName": "cmo_first_name",
"value": "John"
}
],
"viewName": "masters",
}
Use the following request to get the list of all attributes with overrides and their values before the override has been set. The request body is empty.
Request
GET /master/{viewName}/{entity}/{id}/override
Response
{
"recordType": "master",
"entityType": "party",
"recordId": 1982,
"overrides": [
{
"attributeName": "cmo_first_name",
"value": "John"
},
{
"attributeName": "cmo_last_name",
"value": "Smith"
}
],
"viewName": "masters",
}
Setting Overrides
Use the following request to set overrides on one or several attributes.
Specify both the attributeName
and value
in the request body.
The response is empty.
Request
PUT /master/{viewName}/{entity}/{id}/override
{
"overrides": [
{
"attributeName": "cmo_first_name",
"value": "John"
},
{
"attributeName": "cmo_last_name",
"value": "Smith"
}
]
}
Deleting Overrides
Use the following request to delete an override on a particular attribute. Both the request and response body are empty.
Request
DELETE /master/{viewName}/{entity}/{id}/override/{attributeName}
Use the following request to delete all overrides currently set on a record. Both the request and response body are empty.
Request
DELETE /master/{viewName}/{entity}/{id}/override
Stream Consumers
Use the following request to start a stream consumer <crm_stream_name>
.
Request
POST /api/rest/interfaces/streaming/consumers/<crm_stream_name>/start
Use the following request to stop a stream consumer <crm_stream_name>
.
Request
POST /api/rest/interfaces/streaming/consumers/<crm_stream_name>/stop
Use the following request to start all stream consumers.
Request
POST /api/rest/interfaces/streaming/consumers/start
Use the following request to stop all stream consumers.
Request
POST /api/rest/interfaces/streaming/consumers/stop
Purge
Use the following request to initiate a housekeeping procedure.
Completely purges all records with eng_existing=0
and deletion_tid
< TREF
in the _EXPORT_REG
table, which means that the operation does not purge records until the information about logical deletion is provided in incremental exports that these records are part of.
It is also possible to provide the names of incremental exports that should be ignored as the request body.
Request
POST /api/rest/purge/
{"ignored": ["string"]}
The operation is visible in the ONE Runtime Server Admin under MD Process Monitoring > Execution Status (see MD Process Monitoring).
Persistence
Use the following request to drop indices in VLDB persistences. If some indices were created/deleted manually by a user, the operation will fail.
Request
DELETE /api/rest/persistence/indices
Use the following request to create indices in VLDB persistences. If some indices were created/deleted manually by a user, the operation will fail.
Request
POST /api/rest/persistence/indices
Use the following request to start the LTC (transaction garbage collector) for all VLDB persistences.
Request
POST /api/rest/persistence/triggerLtc
Use the following request to start the LTC for the VLDB persistence {name}
.
Request
POST /api/rest/persistence/{name}/triggerLtc
System Parameters
Prints out the currently set runtime parameters (see Runtime Parameters).
http://localhost:9090/api/rest/parameters
Source Systems
List the source systems and information about them.
/source-systems
/source-systems/{name}
Tasks (System Tasks)
Provides information about active and finished system tasks, identical to what is provided under MD Process Monitoring > Execution Status (see MD Process Monitoring) in the ONE Runtime Server Admin.
Query parameters offset
and count
are not compulsory; if they are not present, default values are used instead.
/tasks
/tasks?offset=0&count=5
/tasks/active
/tasks/active?offset=0&count=5
/tasks/finished
/tasks/finished?offset=0&count=5
/tasks/task/{id}
Event Handlers
Provides information about the event handlers, identical to what is provided under MD Process Monitoring > Execution Status (see MD Process Monitoring) in the ONE Runtime Server Admin.
Query parameters offset
and count
are not compulsory; if they are not present, default values are used instead.
/event-handlers
/event-handlers?offset=0&count=5
/event-handlers/finished
/event-handlers/finished?offset=0&count=5
/event-handlers/finished/{id}
Statistics
Shows various statistics regarding instance types, instance records, master views, and their records. The information is identical to what is provided under MD Process Monitoring > Data Statistics (see MD Process Monitoring) in the ONE Runtime Server Admin.
/statistics/instance
/statistics/master
Other Interfaces
The endpoints indicated below show interfaces which provide information about MDM configuration.
-
Services: Shows a list of deployed native SOAP services and their endpoints.
-
Batch exports and Batch loads: Show a list of batch operations and loads which are unavailable.
-
Streaming consumers: Shows a list of streaming consumers which are configured, get name and status.
-
Operation plan: Shows the MDM engine’s order of executing different consolidation sub-tasks when loading/processing data (that is, cleansing, matching and merging of specific entities).
/interfaces/services
/interfaces/batch/exports
/interfaces/batch/loads
/interfaces/streaming/consumers
/operation-plan
Was this page useful?