Concepts: Write & Delete APIs

The Authzed API supports two operations to update tuples in the system: Write and Delete. Both operations exist under the same call.

Create#

The Create operation is used to create new tuples in the Authzed data layer, thereby defining relationships between objects.

Delete#

The Delete operation is used to remove tuples from the Authzed data layer

Touch#

The Touch operation is a special operation which will perform an upsert-like operation, inserting a new tuple if one doesn't exist and updating the transaction-time on a tuple if it does.

warning

Since Touch requires checking if a tuple exists and, if present, updating its transaction-time by re-inserting it if it does, it is a much heavier operation than a simple Create. Touch should only be used for operations where a tuple needs to be marked as "fresh".

Calling the Write API#

To change one or more tuples, issue a WriteRequest API call:

WriteRequest {
updates {
...
}
}

Each update consists of an operation to perform (CREATE, DELETE or TOUCH) and the tuple to update:

WriteRequest {
updates {
RelationTupleUpdate {
operation: CREATE
tuple: RelationTuple { .... }
}
RelationTupleUpdate {
operation: DELETE
tuple: RelationTuple { .... }
}
}
}

The result of the write (if it succeeds) contains a Zookie.

Preconditions#

The Write API supports a section called write_conditions, which is a list of tuples that must exist in Authzed before the updates will occur; if any of the tuples are missing, the write will fail with an error code. Preconditions are typically used as a locking mechanism, to ensure distributed writers can coordinate.

Example:

WriteRequest {
write_conditions {
RelationTuple { .. must exist .. }
}
updates {
RelationTupleUpdate {
operation: CREATE
tuple: RelationTuple { .... }
}
RelationTupleUpdate {
operation: DELETE
tuple: RelationTuple { .... }
}
}
}