Traversal

Content in Cloud CMS is stored in a graph-like structure that consists of nodes and associations. Nodes are entities
in the graph and associations are the relationships (the lines between points in the graph).

As such, when working with content in Cloud CMS, you'll often find it useful to employ these structures in terms of
your content model. Your content can be spread out between nodes and associations equally so that both the entities
and the relationships hold JSON properties that are of interest from a query and search perspective. You may choose
to query one or the other at runtime to determine things about your content structure (indeed, the query and search
engines work equivalently well for both nodes and associations as both are thought of as first class citizens).

Traversals offer a way for you to walk the graph of the relationships to find content that fits a certain shape
within the graph. In essence, they provide a way for you to describe a starting point and a distance away from that
starting point in terms of discovering matching nodes to return in the result set.

One analogy for traversals might be a geographical one. Suppose you were looking for restaurants and you wanted to
find someplace that sold chinese food. You could open the phone book and you'd find a lot of places. But you might
want to further specify things so as to say, "I want Chinese food that is 1 minute driving or less from 27th Street
and Grange Avenue in Greenfield, Wisconsin". Now you're doing a traversal. You start at that location and then
look for places around it that match that constraint.

And you find the House of Fong. (Editor's Note: They had good egg rolls when I was a kid)

When talking about traversals in the Content Graph, the concept is similar. The only difference is that you think
of distance as the number of "hops" away from a node (which is to say, the depth or the number of
associations you need to move away from a node before it's considered too far away).

Traversals let you describe the depth as well as the kind of relationships (i.e. the association type) to travel
along. They also let you describe the kinds of content to hand back. With traversals, you generally describe
the "shape" of the space you're looking in and how to detect matches based on content type.

Permissions

As with everything Cloud CMS, the traversal API respects the underlying permissions and authorities that have been granted
to the objects that are considered result candidates. Authorities are checked before content is retrieved which means
that two people could execute the same traversal and get different results.

Permissions are baked into Cloud CMS all the way down to the core. If you need to get back the full set of content
objects for purposes of synchronization or anything else, make sure that you have sufficient authorities to do so.

Traversal API

The Traversal REST API assumes a repository and branch that identifies where your content lives. It also requires
a starting node from which the traversal begins.

POST /repositories/{repositoryId}/branches/{branchId}/nodes/{nodeId}/traverse

The content type should be application/json and the JSON payload should look like this:

{
    "associations": {
        "a:child": "ANY",
        "a:knows": "INCOMING",
        "a:related": "OUTGOING"
    },
    "depth": 2,
    "types": [ 
        "custom:type1", 
        "custom:type2" 
    ]
}

The associations tells Cloud CMS how to deal with associations that are candidates to be traversed.
When an association is encountered, this block tells Cloud CMS when to traverse it (such as when the association is
an outgoing association, or when it's incoming, or either way).

The depth number tells Cloud CMS how many hops away from the starting point to traverse.

Finally, the types array indicates the kinds of nodes to hand back.

You can also set:

• order - the search order - either BREADTH_FIRST or DEPTH_FIRST.
• filter - nodes to be included - either ALL or ALL_BUT_START_NODE.

Response

The response comes back in a structure like this:

{
    "node": "{nodeId}",
    "config": {},
    "node_count": 0,
    "nodes": {},
    "association_count": 0,
    "associations": {}
}

All of the discovered node come back in the nodes block. If you specified node types, this block
will be constrained only to nodes of that type. The associations come back in the associations
block. This will consist of any associations that were successfully traversed and may be constrained by
any association types you provide.

Note that the response does not come back in a tree structure and that it does not support pagination. To
enable pagination, please refer to the
composite find function which allows you to mix traversal
with search and query. This also allows you to paginate responses.

Example Payloads

Here is an example where we find all nodes that are 1 hop away from a given node. The filter
attribute can be used to describe filters that should be applied to the traversal. By default, the filter
is ALL which indicates to include all nodes, including the start node.

{
    "depth": 1
}

Here is an example where we find all nodes that are 1 hop away from a given node. In this case, we set the
filter to ALL_BUT_START_NODE to have it exclude the start node from the result set.

{
    "depth": 1,
    "filter": "ALL_BUT_START_NODE"
}

Here is an example where we search for nodes that are 2 hops away. We only want nodes to come back that are of
type my:article. The lookup order is BREADTH_FIRST by default.

{
    "depth": 2,
    "types": ["my:article"]
}

We can also instruct the traversal to use a DEPTH_FIRST traversal order. This will alter the
order of items in the result set and can be useful from a pagination perspective, depending on the order that your
users will expect items to appear.

{
    "depth": 2,
    "types": ["my:article"],
    "order": "DEPTH_FIRST"
}

Combining Traversal with Search and Query

For information on mixing traversals with search and query, please take a look at
the documentation on Find.