Read Relationship Operation

The read relationship operation returns property values for a relationship in a Context Graph model.

HTTP GET URL Format

The request is specified as follows. The Spectrum server supports both HTTP and HTTPS.

GET http://server_name:port/rest/DataHub/operations/modelName/relationships/relationshipLabel?query_parameters

URL Path Elements

modelName: The name of the Context Graph model.
relationshipLabel: The name of the relationship label connecting two entities in a model.

Query Parameters


Parameter	Type	Required	Description
sourceID	string	yes	The source ID of the entity that connects a relationship. This parameter specifies an entityType:entityLabel value pair.
targetID	string	yes	The target ID of the entity that connects a relationship. This parameter specifies an entityType:entityLabel value pair.
uniqueID	string	no	The value that distinguishes a relationship when there are multiple relationships with the same label connecting two entities in a model.
retrieveHistory	boolean	no	Set this parameter to true to retrieve the relationship history. The history includes values for each iteration in the history along with changes. The default is false.

Return codes

The operation returns the status code "200 OK" when it is successful. The operation returns the status code 500 (Error) when it fails.

Response without history

The response returns a name-value pair for each relationship property in the following format, when a relationship has N properties.

{"result":{
    "Property1":"Value1",
    "Property2":"Value2",
     ...
    "PropertyN":"ValueN"
 }}

JSON response without history

The following request reads properties from the Roomate relationship label in the "911" model between two person entities.

GET http://localhost:8080/rest/DataHub/operations/911/relationships/Roomate?sourceID=Person:Ahmed%20al-Haznawi&targetID=Person:Ziad%20Jarrah

This results in the following response:

{"result":{
    "Date":1275782400000,
    "Rank":"0"
    }}

Note: Date, time, and date-time property values are UNIX Epoch time values formatted as long data type in both requests and responses.

Response with relationship history

The response returns a historical record for changes to properties in the relationship.

{"result":{
    "property":"value",
    "property":"value",
    ...
    "property":value
    },
    "history": [   {
    "stpId": "relationshipLabel",
    "eventType": "Create|Update|Delete",
    "sourceStpId": "entityType:entityLabel",
    "targetStpId": "entityType:entityLabel",
    "versionDatetime": epic_timestamp,
    "versionDatetimeNanos": epic_timestamp(nanos),
    "username": "userName",
    "changes":       [
    {
    "name": "property",
    "eventType": "Create|Update|Delete",
    "to": value
    },
    ...
    {
    "name": "property",
    "eventType": "Create|Update|Delete",
    "to": value
    }
    ]
    }]
}

JSON response with relationship history

The following request reads properties from the BanksAt relationship between two entities in the Customer Banking model.

GET http://localhost:8080/rest/DataHub/operations/CustomerBanking_DataType/relationships/BanksAt?sourceID=Person%3AJohn%20Smith&targetID=Bank%3ABank%20of%20America&retrieveHistory=true

This results in the following response:

{
   "result":    {
      "OpenTime": 49524000,
      "Float": 2123.98,
      "OpenDateTime": 1275831924000,
      "OpenDate": 1275782400000,
      "Long": 2200007654021,
      "Double": 21.05
   },
   "history": [   {
      "stpId": "BanksAt",
      "eventType": "Create",
      "sourceStpId": "Person:John Smith",
      "targetStpId": "Bank:Bank of America",
      "versionDatetime": 1594398241650,
      "versionDatetimeNanos": 274992488700358,
      "username": "hub_security_allperm",
      "changes":       [
                  {
            "name": "Double",
            "eventType": "Create",
            "to": 21.05
         },
                  {
            "name": "Float",
            "eventType": "Create",
            "to": 2123.98
         },
                  {
            "name": "Long",
            "eventType": "Create",
            "to": 2200007654021
         },
                  {
            "name": "OpenDate",
            "eventType": "Create",
            "to": 1275782400000
         },
                  {
            "name": "OpenDateTime",
            "eventType": "Create",
            "to": 1275831924000
         },
                  {
            "name": "OpenTime",
            "eventType": "Create",
            "to": 49524000
         }
      ]
   }]
}