Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: update data bundles content #921

Merged
merged 1 commit into from
Dec 5, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 39 additions & 31 deletions docs/docs/bundle.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,54 +5,62 @@ sidebar_label: Data Bundles
slug: /api-overview/bundle
---

We introduce a new services to model how relationships and attributes are created and deleted when actions occur on resources. Managing these data centrally promises better transparency and consistent modeling.
## What is Data Bundles

## How Bundles Works
Ensuring that authorization data remains in sync with the business model is an important practice when using Permify.

Let's examine how Bundles operates with basic example.
Prior to Data Bundles, it was the responsibility of the services (such as [WriteData](./api-overview/data/write-data.md) API) to structure how relations are created and deleted when actions occur on resources.

With the Data Bundles, you be able to bundle and model the creation and deletion of relations and attributes when specific actions occur on resources in your applications.

We believe this functionality will streamline managing authorization data as well as managing this in a central place increase visibility around certain actions/triggers that end up with data creation.

## How Bundles Works

Let's examine how Bundles operates with basic example.

Let's say you want to model how data will be created when an organization created in your application. For this purpose, you can utilize the [WriteBundle](./api-overview/bundle/write-bundle.md) API endpoint. This API enables users to define or update data bundles, each distinguished by a unique name.

Here's an example body for WriteBundle in this scenario:

```json
"bundles": [
{
"name": "organization_created"
"arguments": [
"creatorID",
"organizationID"
],
"operations": [
{
"relationships_write": [
"organization:{{.organizationID}}#admin@user:{{.creatorID}}",
"organization:{{.organizationID}}#manager@user:{{.creatorID}}",
],
"attributes_write": [
"organization:{{.organizationID}}$public|boolean:false",
],
},
],
},
],
{
"name": "organization_created"
"arguments": [
"creatorID",
"organizationID"
],
"operations": [
{
"relationships_write": [
"organization:{{.organizationID}}#admin@user:{{.creatorID}}",
"organization:{{.organizationID}}#manager@user:{{.creatorID}}",
],
"attributes_write": [
"organization:{{.organizationID}}$public|boolean:false",
],
},
],
},
],
```

Operations represent actions that can be performed on relationships and attributes, such as adding or deleting relationships when certain events occur.

Let's say user:564 creates an organization:789 in your application. According to your authorization logic, this will result in the creation of several authorization data, including relational tuples and attributes, respectively.

* organization:789#admin@user:564
* organization:789#manager@user:564
* organization:789$public|boolean:false
- organization:789#admin@user:564
- organization:789#manager@user:564
- organization:789$public|boolean:false

Instead of using the [WriteData](./api-overview/data/write-data.md) endpoint, you can utilize [RunBundle](./api-overview/data/run-bundle.md) to create this data by simply providing specific identifiers.

An example request of [RunBundle](./api-overview/data/run-bundle.md) for this scenario:
An example request of [RunBundle](./api-overview/data/run-bundle.md) for this scenario:

```json
POST /bundle
BODY
BODY
{
"name": "project_created",
"arguments": {
Expand All @@ -64,13 +72,13 @@ BODY

This will result in the creation of the following data in Permify:

* organization:789#admin@user:564
* organization:789#manager@user:564
* organization:789$public|boolean:false
- organization:789#admin@user:564
- organization:789#manager@user:564
- organization:789$public|boolean:false

## Endpoints

- [WriteBundle](./api-overview/bundle/write-bundle.md)
- [RunBundle](./api-overview/data/run-bundle.md)
- [DeleteBundle](./api-overview/bundle/delete-bundle.md)
- [ReadBundle](./api-overview/bundle/read-bundle.md)
- [ReadBundle](./api-overview/bundle/read-bundle.md)
Loading