Concepts: Expand API

An Expand call is a call to the Authzed API to expand the contents and structure of relation) for a particular object, under a namespace.

Expand calls are usually used when you need to learn the membership of a relation for a particular object: By calling Expand, a tree is returned containing the entire set of Tuples in the relation for that object, as well as how those tuples were "reached", starting at the requested relation.

Forming an Expand#

An Expand call is formed by specifying the relation on which to expand.

Making the Expand call#

To make an expand call, issue an ExpandRequest to the API:

ExpandRequest {
userset: ObjectAndRelation {
namespace: 'thetenant/document'
object_id: 'somedocument'
relation: 'read'
}
}

The Expand call will return the expanded membership tree of the relation.

For example, imagine if we had this relation:

relation {
name: "read"
userset_rewrite {
union {
child { _this {} }
child {
computed_userset { relation: "write" }
}
}
}
}

Calling Expand on read would return something along the lines of:

ExpandResponse {
tree_node: RelationTupleTreeNode{
intermediate_node: SetOperationUserset{
operation: UNION
child_nodes {
RelationTupleTreeNode {
leaf_node {
users {
# NOTE: All the readers
ObjectAndRelation {
namespace: 'thetenant/user'
object_id: 'firstreader'
relation: '...'
}
ObjectAndRelation {
namespace: 'thetenant/user'
object_id: 'secondreader'
relation: '...'
}
}
}
}
RelationTupleTreeNode {
leaf_node {
users {
# NOTE: All the writers, since `write` is included in `read`
ObjectAndRelation {
namespace: 'thetenant/user'
object_id: 'firstwriter'
relation: '...'
}
ObjectAndRelation {
namespace: 'thetenant/user'
object_id: 'secondwriter'
relation: '...'
}
}
}
expanded: ObjectAndRelation{
namespace: 'thetenant/document'
object_id: 'somedocument'
relation: 'write'
}
}
}
}
}
expanded: ObjectAndRelation{
namespace: 'thetenant/document'
object_id: 'somedocument'
relation: 'read'
}
}
}

Notice that the tree matches the structure of the definition of the read relation, and returns all the users found under which subtree.