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.

Sign up for GitHub

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

Jump to bottom

Add documentation for using contextual tuples in Expand API #209

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add documentation for using contextual tuples in Expand API #209

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 1 addition & 1 deletion docs/openapiv2/apidocs.swagger.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

111 changes: 110 additions & 1 deletion openfga/v1/openfga_service.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -342,6 +342,7 @@ service OpenFGAService {
"This is different from the `/stores/{store_id}/read` API in that both users and "
"computed usersets are returned.\n"
"Body parameters `tuple_key.object` and `tuple_key.relation` are all required.\n"
"A `contextual_tuples` object may also be included in the body of the request. This object contains one field `tuple_keys`, which is an array of tuple keys. Each of these tuples may have an associated `condition`.\n"
"The response will return a tree whose leaves are the specific users and usersets. "
"Union, intersection and difference operator are located in the intermediate nodes.\n\n"
"## Example\n"
Expand Down Expand Up @@ -389,7 +390,115 @@ service OpenFGAService {
" }\n"
"}\n"
"```\n"
"The caller can then call expand API for the `writer` relationship for the `document:2021-budget`."
"The caller can then call expand API for the `writer` relationship for the `document:2021-budget`.\n"
"### Expand Request with Contextual Tuples\n"
"\n"
"Given the model\n"
"```python\n"
"model\n"
" schema 1.1\n"
"\n"
"type user\n"
"\n"
"type folder\n"
" relations\n"
" define owner: [user]\n"
"\n"
"type document\n"
" relations\n"
" define parent: [folder]\n"
" define viewer: [user] or writer\n"
" define writer: [user] or owner from parent\n"
"```\n"
"and the initial tuples\n"
"```json\n"
"[{\n"
" \"user\": \"user:bob\",\n"
" \"relation\": \"owner\",\n"
" \"object\": \"folder:1\"\n"
"}]\n"
"```\n"
"\n"
"To expand all `writers` of `document:1` when `document:1` is put in `folder:1`, the first call could be\n"
"\n"
"```json\n"
"{\n"
" \"tuple_key\": {\n"
" \"object\": \"document:1\",\n"
" \"relation\": \"writer\"\n"
" },\n"
" \"contextual_tuples\": {\n"
" \"tuple_keys\": [\n"
" {\n"
" \"user\": \"folder:1\",\n"
" \"relation\": \"parent\",\n"
" \"object\": \"document:1\"\n"
" }\n"
" ]\n"
" }\n"
"}\n"
"```\n"
"this returns:\n"
"```json\n"
"{\n"
" \"tree\": {\n"
" \"root\": {\n"
" \"name\": \"document:1#writer\",\n"
" \"union\": {\n"
" \"nodes\": [\n"
" {\n"
" \"name\": \"document:1#writer\",\n"
" \"leaf\": {\n"
" \"users\": {\n"
" \"users\": []\n"
" }\n"
" }\n"
" },\n"
" {\n"
" \"name\": \"document:1#writer\",\n"
" \"leaf\": {\n"
" \"tupleToUserset\": {\n"
" \"tupleset\": \"document:1#parent\",\n"
" \"computed\": [\n"
" {\n"
" \"userset\": \"folder:1#owner\"\n"
" }\n"
" ]\n"
" }\n"
" }\n"
" }\n"
" ]\n"
" }\n"
" }\n"
" }\n"
"}\n"
"```\n"
"This tells us that the `owner` of `folder:1` may also be a writer. So our next call could be to find the `owners` of `folder:1`\n"
"```json\n"
"{\n"
" \"tuple_key\": {\n"
" \"object\": \"folder:1\",\n"
" \"relation\": \"owner\"\n"
" }\n"
"}\n"
"```\n"
"which gives\n"
"```json\n"
"{\n"
" \"tree\": {\n"
" \"root\": {\n"
" \"name\": \"folder:1#owner\",\n"
" \"leaf\": {\n"
" \"users\": {\n"
" \"users\": [\n"
" \"user:bob\"\n"
" ]\n"
" }\n"
" }\n"
" }\n"
" }\n"
"}\n"
"```\n"
};
}

Expand Down
Loading
Loading