Read Entity Operation

The read entity operation returns property values for an entity 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/entities/entityType/entityLabel?query_parameters

URL Path Elements

modelName: The name of the Context Graph model.
entityType: An entity type defined in the model
entityLabel: The label for an existing entity in the model.

Query Parameters

The following parameters are specified in the query string, preceded in the URL by the question mark (?). Combine parameter name and value pairs with the ampersand (&).


Parameter	Type	Required	Description
retrieveHistory	Boolean	no	Set this parameter to true to retrieve the entity history. The history includes values for each iteration in the history along with changes. The default is false.
includeRelationshipHistory	Boolean	no	This parameter may be used with the retrieveHistory parameter to add the history for connected relationships. Set this parameter to true to include the relationship history. 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 entity property in the following format. Note that numeric values are not enclosed between quotation marks.

{
   "result":{
   "property":value,
   "property":value,
                ...
   "property":value
}}

JSON response without history

The following request reads properties from the "Place" entity type in the "911" model with the label "FlightSafety International".

GET http://localhost:8080/rest/DataHub/operations/911/entities/Place/FlightSafety%20International

This results in the following response:

{"result":{
                "Latitude":"27.6386433",
                "Location":"Vero Beach, Florida",
                "Longitude":"-80.39727",
                "Place":"FlightSafety International",
                "Date":1275782400000
                }}

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 entity history

The response when you include the retrieveHistory parameter includes values for each historical instance. Inclusion of from and to values in the history depend on whether the eventType is Create, Update, or Delete.

{
   "result":    {
      "property": value,      
      property: value,
        ...
      property: value
   },
"history":    [
            {
         "stpId": "entityType:entityLabel",
         "eventType": "Create|Update|Delete",
         "versionDatetime": epoch_timestamp,
         "versionDatetimeNanos": epoch_timestamp(nanos),
         "username": "userName",
         "edgeChanges": [],
         "properties":          [
                        {
               "name": "property",
               "eventType": "Create|Update|Delete",
               "to": value
            },
            ...
                        {
               "name": "property",
               "eventType": "Create|Update|Delete",
               "to": value
            }
         ]
      }

JSON response with entity history

The following request reads properties from the "John Smith" entity in the Customer Banking model

GET http://localhost:8080/rest/DataHub/operations/CustomerBanking_DataType/entities/Person/John%20Smith?retrieveHistory=true&includeRelationshipHistory=false

This results in the following response:

{
   "result":    {
      "USCitizen": true,      
      "Name": "John Smith",
      "AccountNumber": 9955420
   },
"history":    [ {    
    "stpId": "Person:John Smith",
    "eventType": "Create",
    "versionDatetime": 1594590216325,
    "versionDatetimeNanos": 120456689138214,
    "username": "hub_security_allperm",
    "edgeChanges": [],
    "properties":  [ 
    {
        "name": "AccountNumber",
        "eventType": "Create",
        "to": 9955420
    },
    {
        "name": "Name",
        "eventType": "Create",
        "to": "John Smith"
     },
     {
        "name": "USCitizen",
        "eventType": "Create",
        "to": true
     }
  ]
}

Response with entity relationship history

The response when you include the includeRelationshipHistory parameter includes values for each connected relationship. Inclusion of from and to values in the history depend on whether the eventType is Create, Update, or Delete.

{
    "result":    {
        "parameter": value,
        ...
        "parameter": value
    },
    "history":    [ {
        "stpId": "entityType:entityLabel",
        "eventType": "Create|Update|Delete",
        "versionDatetime": epoch_timestamp,
        "versionDatetimeNanos": epoch_timestamp(nanos),
        "username": "userName",
        "edgeChanges": [ {
        "stpId": "relationshipLabel",
        "eventType": "Create|Update|Delete",            
        "sourceStpId": "entityType:entityLabel",            
        "targetStpId": "entityType:entityLabel",
        "versionDatetime": epoch_timestamp,
        "versionDatetimeNanos": epoch_timestamp(nanos),
        "username": "userName",
        "changes": [ {
            "relationshipProperty": "value",
            "eventType": "Create|Update|Delete",
            "to": value
         }]
    }],
    "properties": []
},

JSON response with entity relationship history

The following request reads properties from the "John Smith" entity and connected relationships in the Customer Banking model.

GET http://localhost:8080/rest/DataHub/operations/CustomerBanking_DataType/entities/Person/John%20Smith?retrieveHistory=true&includeRelationshipHistory=true

This results in the following response:

{
    "result":    {
        "USCitizen": false,
        "Name": "John Smith",
        "AccountNumber": 995542
        },
    "history":    [ {
        "stpId": "Person:John Smith",
        "eventType": "Update",
        "versionDatetime": 1594398222284,
        "versionDatetimeNanos": 274973121721755,
        "username": "hub_security_allperm",
        "edgeChanges": [         {
        "stpId": "LivesAt",
        "eventType": "Create",            
        "sourceStpId": "Person:John Smith",            
        "targetStpId": "Address:123 Main Street",
        "versionDatetime": 1594398222284,
        "versionDatetimeNanos": 274973121721755,
        "username": "hub_security_allperm",
        "changes": [            {
        "name": "PostalCode",
        "eventType": "Create",
        "to": 21119
        }]
    }],
    "properties": []
},