Overview
The Secure Graph service provides a REST interface to store information about a customer's activity to a graph database and to build the customer's profile. Additionally, the Secure Graph service provides consumption layer functionality. A tenant can fetch all data stored in the profile database by all its customers.
The Secure Graph service is used by the enrichers that the tenant is subscribed to in order to build a customer's profile. Data is stored in the graph database as nodes and relations in an encrypted format.
API Reference
/{tenant}/nodes/{namespace}/{type}
/{tenant}/nodes/{namespace}/{type}
Returns number of nodes stored in database with given type and tenant. Requires scope hybris.profile_graph_view.
Returns nodes of given type and optionally filtered by property. Requires scope hybris.profile_graph_view.
/{tenant}/nodes/{namespace}/{type}/{id}
Allows to create a node in the secure graph in the idempotent manner. If the node does not exist then it will be created. Requires scope hybris.profile_graph_manage.
Allows to delete a node in the secure graph in the idempotent manner. Requires scope hybris.profile_graph_manage.
Gets a nodes all properties (with it's id). Requires scope hybris.profile_graph_view.
/{tenant}/nodes/{namespace}/{type}/{id}/{propertyKey}
Gets a single property of a node using property key Requires scope hybris.profile_graph_view.
Overwrites a single property on a node. If the node does not exist then it will be created. Requires scope hybris.profile_graph_manage.
/{tenant}/relations/{fromNode}/{toNode}/{relationship}
/{tenant}/relations/{fromNode}/{toNode}/{relationship}
Gets a relationship by type, id and namespace. Requires scope hybris.profile_graph_view.
Creates or update a relationship in the secure graph between source and target node. The payload are additional arbitrary properties for relation. If start or end node does not exist, it is created automatically. Requires scope hybris.profile_graph_manage.
Allows to delete a relationship in the secure graph in the idempotent manner. Requires scope hybris.profile_graph_manage.
/{tenant}/counters/{fromNode}/{toNode}/{relationship}/{counterName}
/{tenant}/counters/{fromNode}/{toNode}/{relationship}/{counterName}
Increments the counter between two nodes by one. No payload needed. In case any of the start/end nodes is not existing there are crated automatically. Requires scope hybris.profile_graph_manage.
/{tenant}/neighbours/{fromNode}
/{tenant}/neighbours/{fromNode}
Returns all nodes which are NO FURTHER AWAY THAN JUST 1 EDGE from the uniquely defined node (e.g. session). The first returned node is a source node. Requires scope hybris.profile_graph_view.
Data types and consents
Two kinds of data can be stored in the graph database:
- data that belongs to the end customer
- data that belongs to the tenant
In cases where the data is owned by the end customer, such as credit card information, data owned by one end customer cannot be overwritten by data belonging to another end customer. For example, Luke Skywalker's credit card details cannot be overwritten by Han Solo's credit card details. The end customer's data is written on his behalf using the consent-reference mechanism. Luke Skywalker's data can be overwritten only if the Secure Graph service is called with this consent-reference.
In the case of data owned by the tenant, such as Product data, the data can be modified by any tenant's customer activity. For example, the product description can be overwritten when calling the Secure Graph service with any consent-reference of this tenant's customers (Luke Skywalker's, Han Solo's, and such).
The Secure Graph service provides endpoints to create and modify a node and to create and modify a relationship. When one of these endpoints is called the first time, the service creates a new node/relationship in the profile database. On the other hand, when a node/relationship exists in the database, calling the endpoint only appends the properties defined in the call and does not change the other properties.
All data are encrypted and can be retrieved only if proper consents are granted.
If consent is revoked, either by the tenant or the end customer, the data stored in the node are not available. When a request is sent to read a single node/relationship, and the consent to the whole node/relationship revoked, the Secure Graph service returns a response with the status 403.
When consent to the whole node/relationship is granted, but consents to specific properties of some nodes/relationships are revoked, then the Secure Graph service returns only the node/relationships without those revoked properties.
Information about the node/relationship for which consents are revoked can be read by the neighbours endpoints, but the returned data contains only basic information (without customer-specific properties). These nodes or relationships are marked with the flag locked.
For more details, see the Consumption Layer topic.
The consent reference value is required only to create or modify a node/relationship. It is not needed to read or delete a single node or relationship or to fetch stored data using a consumption layer.
The enrichers can only store data in the Secure Graph that is defined in the metamodel and that has proper consents.
Consumption layer
The Secure Graph service's consumption layer is provided by the neighbours endpoint. This endpoint returns details about the provided node and all of the nodes directly connected to it.
Data from the consumption layer can only be retrieved when an access token is provided with the scope hybris.profile_graph_view.
When retrieving data about a customer's profile, the Secure Graph service tries to decrypt the data. If it succeeds, the requester receives real data. If the decryption of the node or relationship fails, the returned element contains only basic information, without the specific properties stored by the enrichers, and has the attribute locked = true.
The node or relationship is returned with the flag "Locked" = "true" in these situations:
- The end customer revoked consent to the whole node or relationship, for example, Session.
- The tenant revoked consent to the whole node or relationship, for example, Product, or other data that is encrypted with a tenant key.
When consent to a node or relationship's property is revoked by the customer or tenant, the key that is used to encrypt data is removed. Therefore, the stored data can't be decrypted anymore. After consent is granted again, a new key is generated, but it is not possible to decrypt any old data.
For more information about consent or encryption keys, see the Consent service documentation.
Secure Graph events
The Secure Graph service sends notifications about changes that enrichers introduce to the SAP Hybris Profile database. Currently, the Secure Graph service only sends notifications about the creation and deletion of nodes and relations. For each change, the Secure Graph service stores one or more new events in the Context service. Every notification event has a new, unique context trace ID.
Create nodes
Upon the creation of a new node, the Secure Graph stores the new event in the Context service with:
- operation: The type of operation, CREATE
- schema: The schema defining the created node, such as
https://api.beta.yaas.io/metamodel/v1/nodes/commerce/Product - message:
{
"id": "as10",
"consentRefId": "ae3ade81-052f-4f36-8825-f1617180ed5e"
}
Attributes of the message:
- id: An identifier of the created node
- consentRefId: Consent reference used in the call to the Secure Graph service
For more details about the structure of the message that an enricher receives, see the Context events section of the Context service document.
Delete nodes
Upon the deletion of a node, the Secure Graph stores the new event in the Context service with:
- operation: The type of operation, DELETE
- schema: The schema defining the deleted node, such as
https://api.beta.yaas.io/metamodel/v1/nodes/commerce/Product - message:
{
"id": "as10",
"consentRefId": "ae3ade81-052f-4f36-8825-f1617180ed5e"
}
Attributes of the message:
- id: An identifier of the deleted node
- consentRefId: Effective consent reference (one that is saved in the database)
Create relation
When the changes that an enricher introduces to the graph result in the creation of a new relation, the Secure Graph stores the new event in the Context service with:
- operation: The type of operation, CREATE
- schema: The schema defining the created relation, such as
https://api.beta.yaas.io/metamodel/v1/relations/commerce/Session/commerce/Product/commerce/VIEWED - message:
{
"consentRefId": "ae3ade81-052f-4f36-8825-f1617180ed5e",
"fromId": "as10",
"toId": "as11",
"relationshipId": "1"
}
Attributes of the message:
- consentRefId: Consent reference used in the call to the Secure Graph
- fromId: The identifier of the source node of the created relation
- toId: The identifier of the destination node of the created relation
- relationshipId: The identifier of the created relation
Delete relation
When the changes that an enricher introduces to the graph result in the deletion of a relation, the Secure Graph stores the new event in the Context service with:
- operation: The type of operation, DELETE
- schema: The schema defining the deleted relation, such as
https://api.beta.yaas.io/metamodel/v1/relations/commerce/Session/commerce/Product/commerce/VIEWED - message:
{
"consentRefId": "ae3ade81-052f-4f36-8825-f1617180ed5e",
"fromId": "as10",
"toId": "as11",
"relationshipId": "1"
}
Attributes of the message:
- consentRefId: Effective consent reference (one that is saved in the database)
- fromId: The identifier of the source node of the deleted relation
- toId: The identifier of the destination node of the deleted relation
- relationshipId: The identifier of the deleted relation
Graph Explorer
The Graph Explorer is a debugging tool that visually represents the profile data stored in the graph. By using this tool, you can view parts of the profile data, and verify if the data is stored with the expected nodes and relationships among nodes.
For more details about the Graph Explorer, and instructions how to use it, see the Graph Explorer documentation.
Introduction to Tutorials
All tutorials are designed so that you can read the tutorial and check it using the API Console while interactively learning how to use the service.
Prerequisites
To follow these tutorials, you must have a valid Bearer access token with the appropriate scope:
- hybris.profile_graph_view - for reading graph data and for all consumption layer operations.
- hybris.profile_graph_manage - for graph data modifications, such as create, update, or delete node or relation.
For more information about how to get an access token, see the '/token' endpoint section of the OAuth2 service documentation.
Nodes endpoint
The Secure Graph service's nodes endpoint enables you to create, update, get, or delete a single node.
Create and update nodes
The Secure Graph service provides an endpoint to store single nodes in a profile database. You can use it to create a new node or update an existing one.
cURL command pattern
curl -X PUT -H "Authorization: Bearer access_token" -H "consent-reference: consent-reference" -H "Content-Type: application/json" -d '{
"some" : "custom property"
}' "https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/nodes/{namespace}/{type}/{id}" -i
Parameters
- Headers
- Authorization: Includes a valid Bearer access token with the hybris.profile_graph_manage scope
- consent-reference: Consent reference of the node's owner
- URI parameters
- {tenant}: Your tenant name
- {namespace}: Namespace of the node
- {type}: Type of node
- {id}: Native ID of the node (Special characters must be URL encoded.)
Example of a PUT request with real data
curl -X PUT -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" -H "consent-reference: 965dcef9-da77-40bf-9e9b-65fd735df113" -H "Content-Type: application/json" -d '{
"name" : "Asterix and Obelix", "description" : "Adventures of Asterix and Obelix", "price" : "$10"
}' "https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/nodes/commerce/Product/1" -i
Response
The response should include the following:
- Status code: A status code of
204indicates that the node was successfully created.
400.Get single nodes
cURL command pattern
curl -X GET -H "Authorization: Bearer access_token" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/nodes/{namespace}/{type}/{id}'
Parameters
- Headers
- Authorization: Includes a valid Bearer access token with the hybris.profile_graph_view scope
- URI parameters
- {tenant}: Your tenant name
- {namespace}: Namespace of the node
- {type}: Type of node
- {id}: Native ID of the node (Special characters must be URL encoded.)
Example of a GET request with real data
curl -X GET -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/nodes/commerce/Product/1'
Response
The response should include the following:
- Status code: A status code of
200indicates that the request has succeeded. - Body:
{ "id" : "1", "consent-reference" : "TENANT", "created" : 1453209636871, "createdByHybrisClient" : "hybris.someEnricher", "tenant" : "mycomicsshop", "schema" : "https://api.beta.yaas.io/hybris/metamodel/v1/nodes/commerce/Product", "name" : "Asterix and Obelix", "description" : "Adventures of Asterix and Obelix", "price" : "$10" }
Delete nodes
cURL command pattern
curl -X DELETE -H "Authorization: Bearer access_token" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/nodes/{namespace}/{type}/{id}' -i
Parameters
- Headers
- Authorization: Includes a valid Bearer access token with the hybris.profile_graph_manage scope
- URI parameters
- {tenant}: Your tenant name
- {namespace}: Namespace of the node to be deleted
- {type}: Type of the node to be deleted
- {id}: Native ID of the node to be deleted (Special characters must be URL encoded.)
Example of a DELETE request with real data
curl -X DELETE -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/nodes/commerce/Product/1' -i
Response
The response should include the following:
- Status code: A status code of
204indicates that the node was successfully deleted.
Get all nodes of the same type and filter by property
The Secure Graph service provides an endpoint that returns all nodes of the same type for a specific tenant. Additionally, the same endpoint allows filtering of the nodes by property. Note that, to apply filtering, the query property must be searchable.
Get all nodes of the same type
cURL command pattern
curl -X GET -H "Authorization: Bearer access_token" -H "consent-reference: consent-reference" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/nodes/{namespace}/{type}'
Parameters
- Headers
- Authorization: Includes a valid Bearer access token with the hybris.profile_graph_view scope
- consent-reference: Consent reference of the node's owner
- URI parameters
- {tenant}: Your tenant name
- {namespace}: Namespace of the node
- {type}: Type of node
- Query parameters
- limit: Limits the number of returned nodes. The parameter is optional. By default, all nodes are returned. For performance reasons, it is recommended to use this parameter whenever possible.
Example of a GET request with real data
curl -X GET -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" -H "consent-reference: fe4e92cf-8a0d-4bb5-a11e-8a300e77563c1" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/nodes/commerce/Address?limit=10'
Response
The response should include the following:
- Status code: A status code of
200indicates that the request has succeeded. The response displays the list of Address-type nodes that are associated with the provided consent reference. - Body:
[
{
"id" : "address1",
"consent-reference" : "fe4e92cf-8a0d-4bb5-a11e-8a300e77563c1",
"created" : 1453209636871,
"createdByHybrisClient" : "hybris.someEnricher",
"tenant" : "mycomicsshop",
"schema" : "https://api.beta.yaas.io/hybris/metamodel/v1/nodes/commerce/Address",
"country" : "PL",
"city" : "Gliwice",
"street" : "Zwyciestwa"
},
{
"id" : "address2",
"consent-reference" : "fe4e92cf-8a0d-4bb5-a11e-8a300e77563c1",
"created" : 1453209636871,
"createdByHybrisClient" : "hybris.someEnricher",
"tenant" : "mycomicsshop",
"schema" : "https://api.beta.yaas.io/hybris/metamodel/v1/nodes/commerce/Address",
"country" : "DE",
"city" : "Muenchen",
"street" : "Nymphenburger Str."
}
]
Filter by property
cURL command pattern
curl -X GET -H "Authorization: Bearer access_token" -H "consent-reference: consent-reference" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/nodes/{namespace}/{type}?q={node property}:"{node property value}"'
Parameters
- Headers
- Authorization: Includes a valid Bearer access token with the hybris.profile_graph_view scope
- consent-reference: Consent reference of the node's owner
- URI parameters
- {tenant}: Your tenant name
- {namespace}: Namespace of the node
- {type}: Type of node
- Query parameters
- q: The query on properties, which consists of a property name and a property value. A property value must be enclosed in quotation marks, and can contain any alphanumeric and white-space characters. Currently the system only supports a single property criterion.
- limit: Limits the number of returned nodes. The parameter is optional. By default, all nodes are returned. For performance reasons, it is recommended to use this parameter whenever possible.
Example of a GET request with real data
url -X GET -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/nodes/commerce/Address?q=country:"PL"'
Response
The response should include the following:
- Status code: A status code of
200indicates that the request has succeeded. - Body:
[
{
"id" : "address1",
"consent-reference" : "fe4e92cf-8a0d-4bb5-a11e-8a300e77563c1",
"created" : 1453209636871,
"createdByHybrisClient" : "hybris.someEnricher",
"tenant" : "mycomicsshop",
"schema" : "https://api.beta.yaas.io/hybris/metamodel/v1/nodes/commerce/Address",
"country" : "PL",
"city" : "Gliwice",
"street" : "Zwyciestwa"
}
]
Filter by non-string property
You can also filter the nodes by a property that is not a string. This example shows how to filter the nodes by the viewCount value:
url -X GET -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/nodes/commerce/categoryAffinity?q=viewCount:1
Update property of a node
The following example shows how to set a single property of a node. If the node does not exist, then it will be created.
cURL command pattern
curl -X PUT -H "Authorization: Bearer access_token" -H "consent-reference: consent-reference" -H "Content-Type: application/json" -d "\"sample property value\"" "https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/nodes/{namespace}/{type}/{id}/{propertyKey}" -i
Parameters
- Headers
- Authorization: Includes a valid Bearer access token with the hybris.profile_graph_manage scope
- consent-reference: Consent reference of the node's owner
- URI parameters
- {tenant}: Your tenant name
- {namespace}: Namespace of the node
- {type}: Type of node
- {id}: Native ID of the node (special characters must be URL encoded)
- {propertyKey} - Name of the node's property
- body
- \"sample property value\" - The value that will be placed in the provided property (in JSON format)
Example of a PUT request with real data
curl -X PUT -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" -H "consent-reference: 965dcef9-da77-40bf-9e9b-65fd735df113" -H "Content-Type: application/json" -d "13" "https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/nodes/commerce/Product/1/edition" -i
Response
The response should include the following:
- Status code: A status code of
204indicates that the property is successfully set.
400.Neighbours endpoint
The neighbours endpoint of the Secure Graph service API Console returns the source node and the nodes directly connected to it. The first returned node is a source node.
cURL command pattern
curl -X GET -H "Authorization: Bearer access_token" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/neighbours/{fromNode}'
Parameters:
- Headers:
- Authorization: Includes valid Bearer access token with the hybris.profile_graph_view scope.
- URI parameters:
- {tenant}: Your tenant name.
- {fromNode}: The attributes of the source node of a relationship: namespace, type, and id. Required format:
{fromNamespace}/{fromType}/{fromId}.- {fromNamespace}: Namespace of the source node.
- {fromType}: Type of the source node.
- {fromId}: Native ID of the source node. Special characters must be URL encoded.
Example of a GET request with real data
curl -X GET -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/neighbours/commerce/Session/123'
Response
The response should include the following:
- Status code: A status code of
200indicates that the source node was found. - Body:
- The first chunk of the response body is for the source node:
{ "id": "123", "tenant": "mycomicsshop", "schema": "https://api.stage.yaas.io/metamodel/v1/nodes/commerce/Session", "neighbours_url": "https://api.stage.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/neighbours/commerce/Session/123", "created": 1459853988325, "createdByHybrisClient" : "hybris.someEnricher", "consentReference": "5b5e1216-4e41-4c5f-b260-23baf48a9e31", "locked": false, "properties": { "resolution": "high" } } - The next chunk of the body is for the neighbour node. A chunk is returned for each neighbour node.
{ "id": "browser_123", "tenant": "mycomicsshop", "schema": "https://api.stage.yaas.io/metamodel/v1/nodes/commerce/Identity", "neighbours_url": "https://api.stage.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/neighbours/commerce/Identity/browser_123", "created": 1459853990029, "createdByHybrisClient" : "hybris.someEnricher", "consentReference": "5b5e1216-4e41-4c5f-b260-23baf48a9e31", "locked": false, "properties": {}, "relations": [ { "id": "1", "fid": "browser_123", "tid": "123", "tenant": "mycomicsshop", "schema": "https://api.stage.yaas.io/metamodel/v1/relations/commerce/Identity/commerce/Session/commerce/LOGGED_IN_TO", "created": 1459853990670, "createdByHybrisClient" : "hybris.someEnricher", "locked": false, "consentReference": "5b5e1216-4e41-4c5f-b260-23baf48a9e31", "properties": { "created": 1459853990670 } } ] }
- The first chunk of the response body is for the source node:
The following placeholder entry is returned for nodes or relations that cannot be properly decrypted (due to missing or invalid consent):
{ "LOCKED" : true }
locked flag, see Consumption Layer.Counters endpoint
The Secure Graph's endpoint counters enable you to increment the counter between two nodes by one.
cURL command pattern
curl -X POST -H "Authorization: Bearer access_token" -H "consent-reference: consent-reference" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/counters/{fromNode}/{toNode}/{relationship}/{counterName}'
Parameters:
- Headers:
- Authorization: Includes a valid Bearer access token with the hybris.profile_graph_manage scope.
- consent-reference: Consent reference of relationship's owner.
- URI parameters:
- {tenant}: Your tenant name.
- {fromNode}: The attributes of the source node of a relationship: namespace, type, and id. Required format:
{fromNamespace}/{fromType}/{fromId}.- {fromNamespace}: Namespace of the relation's source node.
- {fromType}: Type of the relation's source node.
- {fromId}: Native ID of the relation's source node. Special characters must be URL encoded.
- {toNode}: The attributes of the destination node of a relationship: namespace, type, and id. Required format:
{toNamespace}/{toType}/{toId}.- {toNamespace}: Namespace of the relation's destination node.
- {toType}: Type of the relation's destination node.
- {toId}: Native ID of the relation's destination node. Special characters must be URL encoded.
- {relationship}: The attributes of a relationship: namespace, type, and id. Required format:
{relationshipNamespace}/{relationshipType}/{relationshipId}.- {relationshipNamespace}: Relationship namespace.
- {relationshipType}: Relationship type.
- {relationshipId}: Relationship unique identifier. Special characters must be URL encoded.
- {counterName}: Counter name.
Example of a POST request with real data
curl -X POST -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" -H "consent-reference: 965dcef9-da77-40bf-9e9b-65fd735df113" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/counters/commerce/Session/123/commerce/Product/1/commerce/VIEWED/13/viewCount'
Response
The response should include the following:
- Status code: A status code of
200indicates that the query was successfully executed. - Body:
{ "schema": "https://api.beta.yaas.io/metamodel/v1/relations/commerce/Session/commerce/Product/commerce/VIEWED", "fid": "123", "toCreated": 1453284551529, "created": 1453373471235, "createdByHybrisClient" : "hybris.someEnricher", "fSchema": "https://api.beta.yaas.io/metamodel/v1/nodes/commerce/Session", "relationCreated": 1453373471235, "tSchema": "https://api.beta.yaas.io/metamodel/v1/nodes/commerce/Product", "tid": "1", "consentReference": "001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e", "fromCreated": 1453284551529, "id": "13", "viewCount": 3, "tenant": "mycomicsshop" }
Relations endpoint
The Secure Graph service allows you to create, update, get, and delete relations between single nodes.
Create or update a relation
To create or update a relation, use the command shown in the example.
cURL command pattern
curl -X PUT -H "Authorization: Bearer access_token" -H "consent-reference: consent-reference" -H "Content-Type: application/json" -d '{
"test": "test2",
"anotherTest": "anotherTestValue"
}' 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/relations/{fromNode}/{toNode}/{relationship}' -i
Parameters
- Headers
- Authorization: Includes a valid Bearer access token with the hybris.profile_graph_manage scope
- consent-reference: Consent reference of relationship's owner
- URI parameters
- {tenant} Your tenant name
- {fromNode}: The attributes of the source node of a relationship: namespace, type, and id. Required format:
{fromNamespace}/{fromType}/{fromId}.- {fromNamespace}: Namespace of the relation's source node.
- {fromType}: Type of the relation's source node.
- {fromId}: Native ID of the relation's source node. Special characters must be URL encoded.
- {toNode}: The attributes of the destination node of a relationship: namespace, type, and id. Required format:
{toNamespace}/{toType}/{toId}.- {toNamespace}: Namespace of the relation's destination node.
- {toType}: Type of the relation's destination node.
- {toId}: Native ID of the relation's destination node. Special characters must be URL encoded.
- {relationship}: The attributes of a relationship: namespace, type, and id. Required format:
{relationshipNamespace}/{relationshipType}/{relationshipId}.- {relationshipNamespace}: Relationship namespace.
- {relationshipType}: Relationship type.
- {relationshipId}: Relationship unique identifier. Special characters must be URL encoded.
- Body:
{ "test": "test2", "anotherTest": "anotherTestValue" }
Example of a PUT request with real data
curl -X PUT -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" -H "consent-reference: 965dcef9-da77-40bf-9e9b-65fd735df113" -H "Content-Type: application/json" -d '{
"affinity": 123
}' 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/relations/commerce/Session/123/commerce/Product/1/commerce/VIEWED/13' -i
Response
The response should include the following:
- Status code: A status code of
204indicates that the relationship was successfully created.
400.Get relation
cURL command pattern
curl -X GET -H "Authorization: Bearer access_token" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/relations/{fromNode}/{toNode}/{relationship}'
Parameters
- Headers
- Authorization: Includes a valid Bearer access token with the hybris.profile_graph_view scope
- URI parameters
- {tenant}: Your tenant name
- {fromNode}: The attributes of the source node of a relationship: namespace, type, and id. Required format:
{fromNamespace}/{fromType}/{fromId}.- {fromNamespace}: Namespace of the relation's source node.
- {fromType}: Type of the relation's source node.
- {fromId}: Native ID of the relation's source node. Special characters must be URL encoded.
- {toNode}: The attributes of the destination node of a relationship: namespace, type, and id. Required format:
{toNamespace}/{toType}/{toId}.- {toNamespace}: Namespace of the relation's destination node.
- {toType}: Type of the relation's destination node.
- {toId}: Native ID of the relation's destination node. Special characters must be URL encoded.
- {relationship}: The attributes of a relationship: namespace, type, and id. Required format:
{relationshipNamespace}/{relationshipType}/{relationshipId}.- {relationshipNamespace}: Relationship namespace.
- {relationshipType}: Relationship type.
- {relationshipId}: Relationship unique identifier. Special characters must be URL encoded.
Example of a GET request with real data
curl -X GET -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/relations/commerce/Session/123/commerce/Product/1/commerce/VIEWED/13'
Response
The response should include the following:
- Status code: A status code of
200indicates that the request has succeeded. - Body:
{ "fid": "123", "schema": "https://api.beta.yaas.io/metamodel/v1/relations/commerce/Session/commerce/Product/commerce/VIEWED", "consentReference": "965dcef9-da77-40bf-9e9b-65fd735df113", "created": 1453209636877, "createdByHybrisClient" : "hybris.someEnricher", "fSchema": "https://api.beta.yaas.io/metamodel/v1/nodes/commerce/Session", "id": "13", "tSchema": "https://api.beta.yaas.io/metamodel/v1/nodes/commerce/Product", "tid": "1", "tenant": "mycomicsshop" }
Delete relation
cURL command pattern
curl -X DELETE -H "Authorization: Bearer access_token" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/relations/{fromNode}/{toNode}/{relationship}' -i
Parameters
- Headers
- Authorization: Includes a valid Bearer access token with the hybris.profile_graph_manage scope
- URI parameters
- {tenant}: Your tenant name
- {fromNode}: The attributes of the source node of a relationship: namespace, type, and id. Required format:
{fromNamespace}/{fromType}/{fromId}.- {fromNamespace}: Namespace of the relation's source node.
- {fromType}: Type of the relation's source node.
- {fromId}: Native ID of the relation's source node. Special characters must be URL encoded.
- {toNode}: The attributes of the destination node of a relationship: namespace, type, and id. Required format:
{toNamespace}/{toType}/{toId}.- {toNamespace}: Namespace of the relation's destination node.
- {toType}: Type of the relation's destination node.
- {toId}: Native ID of the relation's destination node. Special characters must be URL encoded.
- {relationship}: The attributes of a relationship: namespace, type, and id. Required format:
{relationshipNamespace}/{relationshipType}/{relationshipId}.- {relationshipNamespace}: Relationship namespace.
- {relationshipType}: Relationship type.
- {relationshipId}: Relationship unique identifier. Special characters must be URL encoded.
Example of a DELETE request with real data
curl -X DELETE -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" 'https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/relations/commerce/Session/123/commerce/Product/1/commerce/VIEWED/13' -i
Response
The response should include the following:
- Status code: A status code of
204indicates that the relationship was successfully deleted.
Event scheduling
When sending a PUT or a POST request to the Secure Graph service, you can determine when to send the scheduled event, associated with a created or updated element, such as a node or a relation. To do so, pass hybris-schedule-event-at and, optionally, hybris-schedule-event-parameter as additional headers in your request.
Set the event delivery time for a node
This example shows how to create or update a node while additionally defining when to send a notification about event scheduling to the system.
cURL command pattern
curl -X PUT -H "Authorization: Bearer access_token" -H "consent-reference: consent-reference" -H "hybris-schedule-event-at: schedule_event_at" -H "hybris-schedule-event-parameter: schedule_event_parameter" -H "Content-Type: application/json" -d '{
"some" : "custom property"
}' "https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/nodes/{namespace}/{type}/{id}" -i
Parameters
- Headers
- Authorization: Includes a valid Bearer access token with the hybris.profile_graph_manage scope
- consent-reference: Consent reference of the node's owner
- hybris-schedule-event-at: Provide this value in the ISO 8601 format, for example
2016-12-10T18:06:17.234Z, or as a duration, for exampleP2DT2H30M5S. For duration, the service supports only days, hours, minutes, and seconds. - hybris-schedule-event-parameter: A string that defines additional data, sent with the scheduled event, for example
set affinity to 1,23
- URI parameters
- {tenant}: Your tenant name
- {namespace}: Namespace of the node
- {type}: Type of the node
- {id}: Native ID of the node. Special characters must be URL encoded.
Example of a PUT request with real data
curl -X PUT -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" -H "consent-reference: 965dcef9-da77-40bf-9e9b-65fd735df113" -H "hybris-schedule-event-at: 2016-12-10T18:06:17.234Z" -H "hybris-schedule-event-parameter: affinity=1,23" -H "Content-Type: application/json" -d '{
"name" : "Asterix and Obelix", "description" : "Adventures of Asterix and Obelix", "price" : "$10"
}' "https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/nodes/commerce/Product/1" -i
Examples of store events and scheduled events
This section provides examples of notifications that the Secure Graph service sends when you set the scheduled event delivery time. These notifications are called store events.
Sample store event for a node
The Secure Graph sends an event, associated with a creation or update of a node, to the Context Service with:
- Operation: STORE
- Schema:
core/ScheduledEvent - Payload:
{
"id" : "999",
"schema" : "nodes/commerce/Product",
"consentRefId" : "ae3ade81-052f-4f36-8825-f1617180ed5e",
"scheduleAt" : "2016-12-10T18:06:17.234Z",
"scheduleParameter" : "affinity=1,23",
"scheduleId" : "nodes/commerce/Product/999"
}
Attributes of the message:
- id: The identifier of the created node
- schema: The schema defining the node
- consentRefId: Consent reference of the node's owner
- scheduleAt: Determines when the Context service sends the scheduled event
- scheduleParameter: Determines the scheduled event data
- scheduleId: The unique identifier of the event. If you set scheduleId, the service overwrites all previously-scheduled events with the same scheduleId that are not yet delivered.
This event notifies the Context service that the event delivery time is set.
Sample node scheduled event
At a specified hybris-scheduled-event-at time, the Context service sends a scheduled event with:
- Operation: SCHEDULED
- Schema:
nodes/commerce/Product - Payload:
{
"id" : "999",
"consentRefId" : "ae3ade81-052f-4f36-8825-f1617180ed5e",
"scheduleParameter" : "affinity=1,23"
}
Sample notification event for a node property
The Secure Graph sends an event, associated with an update of a node property, to the Context Service with:
- Operation: STORE
- Schema:
core/ScheduledEvent - Payload:
{
"id" : "999",
"schema" : "nodes/commerce/Product/name",
"consentRefId" : "ae3ade81-052f-4f36-8825-f1617180ed5e",
"scheduleAt" : "2016-12-10T18:06:17.234Z",
"scheduleParameter" : "affinity=1,23",
"scheduleId" : "nodes/commerce/Product/name/999"
}
Attributes of the message:
- id: The identifier of the node
- schema: The schema defining the node property
- consentRefId: Consent reference of the node's owner
- scheduleAt: Determines when the Context service sends the scheduled event
- scheduleParameter: Determines the scheduled event data
- scheduleId: The unique identifier of the event. If you set scheduleId, the service overwrites all previously-scheduled events with the same scheduleId that are not yet delivered.
This event notifies the Context service that the event delivery time is set.
Sample node property scheduled event
At a specified hybris-scheduled-event-at time, the Context service sends a scheduled event with:
- Operation: SCHEDULED
- Schema:
nodes/commerce/Product/name - Payload:
{
"id" : "999",
"consentRefId" : "ae3ade81-052f-4f36-8825-f1617180ed5e",
"scheduleParameter" : "affinity=1,23"
}
Sample notification event for a relation
The Secure Graph sends an event, associated with a creation or update of a relation, to the Context Service with:
- Operation: STORE
- Schema:
core/ScheduledEvent - Payload:
{
"fromId" : "324e32",
"toId" : "81y29u3",
"relationshipId" : "999",
"schema" : "relations/commerce/Session/commerce/Product/commerce/VIEWED",
"consentRefId" : "ae3ade81-052f-4f36-8825-f1617180ed5e",
"scheduleAt" : "2016-12-10T18:06:17.234Z",
"scheduleParameter" : "affinity=1,23",
"scheduleId" : "relations/commerce/Session/324e32/commerce/Product/81y29u3/commerce/VIEWED/999"
}
Attributes of the message:
- fromId: The identifier of the source node of the relation
- toId: The identifier of the destination node of the relation
- relationshipId: The identifier of the relation
- schema: The schema defining the relation
- consentRefId: Consent reference of the relation's owner
- scheduleAt: Determines when the Context service sends the scheduled event
- scheduleParameter: Determines the scheduled event data
- scheduleId: The unique identifier of the event. If you set scheduleId, the service overwrites all previously-scheduled events with the same scheduleId that are not yet delivered.
This event notifies the Context service that the event delivery time is set.
Sample relation schedule event
At a specified hybris-schedule-event-at time, the Context service sends a scheduled event with:
- Operation: SCHEDULED
- Schema:
relations/commerce/Session/commerce/Product/commerce/VIEWED - Payload:
{
"fromId" : "324e32",
"toId" : "81y29u3",
"id" : "999",
"consentRefId" : "ae3ade81-052f-4f36-8825-f1617180ed5e",
"scheduleParameter" : "affinity=1,23"
}
Sample notification event for a relation property
The Secure Graph sends an event, associated with the update of a relation property, to the Context Service with:
- Operation: STORE
- Schema:
core/ScheduledEvent - Payload:
{
"fromId" : "324e32",
"toId" : "81y29u3",
"relationshipId" : "999",
"schema" : "relations/commerce/Session/commerce/Product/commerce/VIEWED/count",
"consentRefId" : "ae3ade81-052f-4f36-8825-f1617180ed5e",
"scheduleAt" : "2016-12-10T18:06:17.234Z",
"scheduleParameter" : "affinity=1,23",
"scheduleId" : "relations/commerce/Session/324e32/commerce/Product/81y29u3/commerce/VIEWED/count/999"
}
Attributes of the message:
- fromId: The identifier of the source node of the relation
- toId: The identifier of the destination node of the relation
- relationshipId: The identifier of the relation
- schema: The schema defining the relation
- consentRefId: Consent reference of the relation's owner
- scheduleAt: Determines when the Context service sends the scheduled event
- scheduleParameter: Determines the scheduled event data
- scheduleId: The unique identifier of the event. If you set scheduleId, the service overwrites all previously-scheduled events with the same scheduleId that are not yet delivered.
This event notifies the Context service that the event delivery time is set.
Sample relation property scheduled event
At a specified hybris-scheduled-event-at time, the Context service sends a scheduled event with:
- Operation: SCHEDULED
- Schema:
relations/commerce/Session/commerce/Product/commerce/VIEWED/count - Payload:
{
"fromId" : "324e32",
"toId" : "81y29u3",
"id" : "999",
"consentRefId" : "ae3ade81-052f-4f36-8825-f1617180ed5e",
"scheduleParameter" : "affinity=1,23"
}
Event tracking
To track events sent when calling the Secure Graph service, pass the contextTraceId as the hybris-context-trace-id header's value. The service returns the contextTraceID as id in the payload of the event sent to the PubSub service.
The contextTraceId defines a business transaction of sorts -- a single event flow from the Context or Edge services to the Secure Graph service. The contextTraceId links events that an enricher receives in the payload from PubSub, and events that an enricher sends to the Secure Graph service.
To monitor a full transaction in SAP Hybris Profile, pass the contextTraceId that an enricher receives to the Secure Graph service, as shown in the example. If there are any problems with event processing, provide system support with the contextTraceID. Propagating contextTraceId from an enricher to the Secure Graph service enables diagnosing tenant-enricher problems.
Propagate contextTraceId to Secure Graph
This example shows how to ensure that the system tracks the node creation and update events.
cURL command pattern
curl -X PUT -H "Authorization: Bearer access_token" -H "consent-reference: consent-reference" -H "hybris-context-trace-id: contextTraceId" -H "Content-Type: application/json" -d '{
"some" : "custom property"
}' "https://api.beta.yaas.io/hybris/profile-secured-graph/v1/{tenant}/nodes/{namespace}/{type}/{id}" -i
Parameters
- Headers
- Authorization: Includes a valid Bearer access token with the hybris.profile_graph_manage scope
- consent-reference: Consent reference of the node's owner
- hybris-context-trace-id: Unique identifier of the event
- URI parameters
- {tenant}: Your tenant name
- {namespace}: Namespace of the node
- {type}: Type of node
- {id}: Native ID of the node, special characters must be URL encoded
Example of a PUT request with real data
curl -X PUT -H "Authorization: Bearer 001-ad2b1327-8888-4ce4-b2cc-d64a9bc4932e" -H "consent-reference: 965dcef9-da77-40bf-9e9b-65fd735df113" -H hybris-context-trace-id: cc5ad0c0-d188-11e6-934a-47dbb9caaa1b-1" -H "Content-Type: application/json" -d '{
"name" : "Asterix and Obelix", "description" : "Adventures of Asterix and Obelix", "price" : "$10"
}' "https://api.beta.yaas.io/hybris/profile-secured-graph/v1/mycomicsshop/nodes/commerce/Product/1" -i
Glossary
| Term | Description |
|---|---|
| authorization | The process of determining whether a given microservice has permission to gain consent. |
| consent | Permission to access (read, write) specific profile data, for example, permission to read/write age estimation or physical address. A consumer and a tenant can grant and revoke consent for subsets of their respective data. |
| consent class | A string alias, defined by developers, that references a set of profile data (also called "schemas") for which consent can be granted and revoked. This string is exposed to users (consumers and tenants) as a reference through which they control consent. For example, the consent class "Purchases" might reference a set of data that includes items purchased, purchase dates, and purchase prices. Toggling consent for "Purchase" would enable and disable consent for that entire set of data. |
| consent reference | A unique, randomized string that serves as a passcode to decrypt data associated with one or more schemas. Various service calls require a consent reference. |
| consumer | The end user whose actions yield profile data in the graph. A profile describes a single consumer. |
| context | Data that affects the state of the graph. This data can be collected from consumer-triggered events or from third-party sources such as weather stations. |
| Context Adapter | A microservice that receives data and, optionally, adapts it for entry into the graph. For example, a context adapter can adapt address data by adding a ZIP code and normalizing the street labels (for example, changing "St" to "Street"). The context adapter then passes the data through the Context service, which caches it so that enrichers can subsequently persist the data in the graph. |
| context repository | A temporary cache for adapted context data, before it is further processed by enrichers and persisted in the graph. |
| context service | An internal microservice that manages the insertion of, and the retrieval of, context data in the Context Repository. |
| encryption key | A unique, randomized string used to encrypt and decrypt specific data in the graph. Each data element is encrypted with a different encryption key. Decryption, using this key, is required to access, view, and alter the data. |
| enricher | A microservice that retrieves data from the Context Repository and/or Graph, possibly alters or extends it, and then persists data in the graph. An enricher can interpret data points, or sets of data points, to yield new data to persist. For example, an enricher can interpret purchasing data and contemporaneous weather station data to yield new data indicating that the consumer is a rainy-day shopper. |
| graph | The database that stores profile data as nodes, edges, and properties, and allows semantic queries. |
| identity | One of many independent units of data used to identify a unique profile, such as an email address, browser type, or version. |
| profile | Data about a single consumer, collected and derived from events that are triggered by, or are logically associated, with that consumer. |
| schema | A string representation of a path in the graph that represents an abstraction, rather than a concrete instance, of a particular data structure. |
| tenant | A registered entity with a shared commercial goal that subscribes to SAP Hybris Profile services and packages to reach that goal. A tenant can also develop and contribute enrichers and context adapters to the SAP Hybris Profile suite. Within YaaS, a tenant is a project. |
If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.
Use our private help channel. Receive updates over email and contact our specialists directly.
If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.