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}

head

Returns number of nodes stored in database with given type and tenant. Requires scope hybris.profile_graph_view.

get

Returns nodes of given type and optionally filtered by property. Requires scope hybris.profile_graph_view.

/{tenant}/nodes/{namespace}/{type}/{id}

put

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.

delete

Allows to delete a node in the secure graph in the idempotent manner. Requires scope hybris.profile_graph_manage.

get

Gets a nodes all properties (with it's id). Requires scope hybris.profile_graph_view.

/{tenant}/nodes/{namespace}/{type}/{id}/{propertyKey}

get

Gets a single property of a node using property key Requires scope hybris.profile_graph_view.

put

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}

get

Gets a relationship by type, id and namespace. Requires scope hybris.profile_graph_view.

put

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.

delete

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}

post

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}

get

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)
If a given node has relations, the Secure Graph removes them along with the node, and sends a notification about a deleted node, and about each deleted relationship.

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.

The service has eventual consistency when storing data. You might not get up-to-date results if you read the data immediately after introducing changes to the graph. For example, when you update a property of a node and then read the data, you might still get the old results from before the update. The service, however, returns the updated data eventually. To mitigate this problem, it is recommended that you implement a personalized solution, such as request buffering.


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.

You can additionally determine when a decay event, associated with a created or updated node, should be sent to the system. To do so, pass hybris-decay-at and, optionally, hybris-decay-parameters as additional headers in your request. For more details, see the Data decay section.

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 204 indicates that the node was successfully created.
Any attempt to update node properties such as id, tid, fid, label, schema, created, createdByHybrisClient or consentReference results in an error with a status code of 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 200 indicates 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

Use caution when deleting nodes. Nodes stored in the profile database can be deleted, but the operation is irreversible. The node cannot be undeleted.

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 204 indicates 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.

The filter-by-property functionality is currently an experimental feature.

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 200 indicates 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 200 indicates 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 204 indicates that the property is successfully set.
Any attempt to set properties such as id, tid, fid, label, schema, created or consentReference results in an error with a status code of 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 200 indicates 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 following placeholder entry is returned for nodes or relations that cannot be properly decrypted (due to missing or invalid consent):

{ "LOCKED" : true }
For more information about the locked flag, see Consumption Layer.


Counters endpoint

The Secure Graph's endpoint counters enable you to increment the counter between two nodes by one.

You can additionally determine when a decay event, associated with the counter, should be sent to the system. To do so, pass hybris-decay-at and, optionally, hybris-decay-parameters as additional headers in your request. For more details, see the Data decay section.

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 200 indicates 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.

You can additionally determine when a decay event, associated with a created or updated relation, should be sent to the system. To do so, pass hybris-decay-at and, optionally, hybris-decay-parameters as additional headers in your request. For more details, see the Data decay section.

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 204 indicates that the relationship was successfully created.
Any attempt to update relation properties such as id, tid, fid, label, schema, created, createdByHybrisClient or consentReference, results in an error with a status code of 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 200 indicates 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

Use caution when deleting relationships. A relationship stored in the profile database can be deleted, but the operation is irreversible. The relationship cannot be undeleted.

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 204 indicates 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 example P2DT2H30M5S. 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
To determine when to send the scheduled event for relations and counters to the system, update the respective cURL commands by including the hybris-schedule-event-at and, optionally, hybris-schedule-event-parameter headers.

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
To track other events, such as the creation or deletion of relations, update the respective cURL commands to include the hybris-context-trace-id header with a valid contextTraceId value.


Glossary

TermDescription
authorizationThe process of determining whether a given microservice has permission to gain consent.
consentPermission 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 referenceA unique, randomized string that serves as a passcode to decrypt data associated with one or more schemas. Various service calls require a consent reference.
consent classA 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.
consumerThe end user whose actions yield profile data in the graph. A profile describes a single consumer.
contextData 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 AdapterA 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 repositoryA temporary cache for adapted context data, before it is further processed by enrichers and persisted in the graph.
context serviceAn internal microservice that manages the insertion of, and the retrieval of, context data in the Context Repository.
encryption keyA 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.
enricherA 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.
graphThe database that stores profile data as nodes, edges, and properties, and allows semantic queries.
identityOne of many independent units of data used to identify a unique profile, such as an email address, browser type, or version.
profileData about a single consumer, collected and derived from events that are triggered by, or are logically associated, with that consumer.
schemaA string representation of a path in the graph that represents an abstraction, rather than a concrete instance, of a particular data structure.
tenantA 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.


  • Send feedback

    If you find any information that is unclear or incorrect, please let us know so that we can improve the Dev Portal content.

  • Get Help

    Use our private help channel. Receive updates over email and contact our specialists directly.

  • hybris Experts

    If you need more information about this topic, visit hybris Experts to post your own question and interact with our community and experts.