Merge pull request #949 from Permify/docs

docs: improvements on endpoints style & content

docs/docs/api-overview/data/delete-data.md

@@ -7,7 +7,10 @@ You can delete any stored relation tuples or attributes with following API
 
 ## Request
 
-**Path:** POST /v1/tenants/{tenant_id}/data/delete
+**Path:** 
+```javascript
+POST /v1/tenants/{tenant_id}/data/delete
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Data/data.delete)
 

docs/docs/api-overview/data/read-attributes.md

@@ -6,8 +6,9 @@ import TabItem from '@theme/TabItem';
 Read API allows for directly querying the stored graph data to display and filter stored attributes.
 
 ## Request
-
-**Path:** POST /v1/tenants/{tenant_id}/data/attributes/read
+```javascript
+POST /v1/tenants/{tenant_id}/data/attributes/read
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Data/data.attributes.read)
 

docs/docs/api-overview/data/read-relationships.md

@@ -6,8 +6,9 @@ import TabItem from '@theme/TabItem';
 Read API allows for directly querying the stored graph data to display and filter stored relational tuples.
 
 ## Request
-
-**Path:** POST /v1/tenants/{tenant_id/data/relationships/read
+```javascript
+POST /v1/tenants/{tenant_id}/data/relationships/read
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Data/data.relationships.read)
 

docs/docs/api-overview/data/run-bundle.md

@@ -9,7 +9,9 @@ encapsulated in a bundle.
 
 ## Request
 
-**Path:** POST /v1/tenants/{tenant_id}/data/run-bundle
+```javascript
+ POST /v1/tenants/{tenant_id}/data/run-bundle
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Data/bundle.run)
 

docs/docs/api-overview/data/write-data.md

@@ -24,7 +24,10 @@ Another example: when one a company executive grant admin role to user (lets say
 You can use the **/v1/tenants/{tenant_id}/data/write** endpoint for both creating **relation tuples** and for creating **attribute data**.
 :::
 
-**Path:** POST /v1/tenants/{tenant_id}/data/write
+**Path:**
+```javascript
+ POST /v1/tenants/{tenant_id}/data/write
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Data/data.write)
 
@@ -136,16 +139,126 @@ curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/data/write
 
 You can use `attributes` argument to create attribute/attributes with a single API call, similarly creating a `relational tuple`. 
 
-Assume we want to both create relational tuple and attribute within in single request. Let's say **user:1** has been granted as editor in **document:1** and **document:1** is a **private (boolean)** document, that only specific users have view access.
+Let's say **document:1** is a **private (boolean)** document, that only specific users have view access - `document:1$is_private|boolean:true`.
 
-Following tuples will be created, respectively,
+:::info Attribute Data Syntax
+As you noticed, the attribute tuple syntax differs from the relationship syntax, structured similarly as: 
+`entity $ attribute | value`
+:::
+
+<Tabs>
+<TabItem value="go" label="Go">
+
+```go
+// Convert the wrapped attribute value into Any proto message
+value, err := anypb.New(&v1.BooleanValue{
+    Data: true,
+})
+if err != nil {
+	// Handle error
+}
+
+cr, err := client.Data.Write(context.Background(), &v1.DataWriteRequest{
+    TenantId: "t1",,
+    Metadata: &v1.DataWriteRequestMetadata{
+        SchemaVersion: "",
+    },
+    Attributes: []*v1.Attribute{
+        {
+            Entity: &v1.Entity{
+                Type: "document",
+                Id:   "1",
+            },
+            Attribute: "is_private",
+            Value:     value,
+        },
+    },
+})
+```
+
+</TabItem>
+
+<TabItem value="node" label="Node">
+
+```javascript
+const booleanValue = BooleanValue.fromJSON({ data: true });
+
+const value = Any.fromJSON({
+    typeUrl: 'type.googleapis.com/base.v1.BooleanValue',
+    value: BooleanValue.encode(booleanValue).finish()
+});
+
+client.data.write({
+    tenantId: "t1",
+    metadata: {
+        schemaVersion: ""
+    },
+    attributes: [{
+        entity: {
+            type: "document",
+            id: "1"
+        },
+        attribute: "is_private",
+        value: value,
+    }]
+}).then((response) => {
+    // handle response
+})
+```
+
+</TabItem>
+<TabItem value="curl" label="cURL">
+
+```curl
+curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/data/write' \
+--header 'Content-Type: application/json' \
+--data-raw '{
+{
+    "metadata": {
+        "schema_version": ""
+    },
+    "attributes": [
+        {
+            "entity": {
+                "type": "document",
+                "id": "1"
+            },
+            "attribute": "is_private",
+            "value": {
+                "@type": "type.googleapis.com/base.v1.BooleanValue",
+                "data": true
+            }
+        }
+    ]
+}
+}'
+```
+
+</TabItem>
+</Tabs>
+
+:::warning Attribute **value** field
+**value** field is mandatory on attribute data creation.
+
+Here are the available attribute value types:
+
+- **type.googleapis.com/base.v1.StringValue**
+- **type.googleapis.com/base.v1.BooleanValue**
+- **type.googleapis.com/base.v1.IntegerValue**
+- **type.googleapis.com/base.v1.DoubleValue**
+- **type.googleapis.com/base.v1.StringArrayValue**
+- **type.googleapis.com/base.v1.BooleanArrayValue**
+- **type.googleapis.com/base.v1.IntegerArrayValue**
+- **type.googleapis.com/base.v1.DoubleArrayValue**
+:::
+
+#### Creating Attributes and Relations In Single Request
+
+Assume we want to both create relational tuple and attribute within in single request. Specifically we want to create following tuples,
 
 -  `document:1#editor@user:1`
 -  `document:1$is_private|boolean:true`
 
-:::info Attribute Data Syntax
-As you noticed, the attribute tuple syntax differs from the relationship syntax, structured as: `entity $ attribute | value`
-:::
 
 <Tabs>
 <TabItem value="go" label="Go">
@@ -276,21 +389,6 @@ curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/data/write
 </TabItem>
 </Tabs>
 
-:::warning Attribute **value** field
-**value** field is mandatory on attribute data creation.
-
-Here are the available attribute value types:
-
-- **type.googleapis.com/base.v1.StringValue**
-- **type.googleapis.com/base.v1.BooleanValue**
-- **type.googleapis.com/base.v1.IntegerValue**
-- **type.googleapis.com/base.v1.DoubleValue**
-- **type.googleapis.com/base.v1.StringArrayValue**
-- **type.googleapis.com/base.v1.BooleanArrayValue**
-- **type.googleapis.com/base.v1.IntegerArrayValue**
-- **type.googleapis.com/base.v1.DoubleArrayValue**
-:::
-
 ## Response
 
 ```json

docs/docs/api-overview/permission/check-api.md

@@ -14,7 +14,10 @@ In this section we'll look at the resource based check request of Permify. You c
 
 ## Request
 
-**Path:** POST /v1/permissions/check
+**Path:** 
+```javascript
+POST /v1/permissions/check
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Permission/permissions.check)
 

docs/docs/api-overview/permission/expand-api.md

@@ -116,7 +116,10 @@ According to above authorization model, let's create 3 example relation tuples f
 
 We can use expand API to reason the access actions. If we want to reason access structure for actions of repository entity, we can use expand API with ***POST "/v1/permissions/expand"***. 
 
-**Path:** POST /v1/tenants/{tenant_id}/permissions/expand
+**Path:** 
+```javascript
+POST /v1/tenants/{tenant_id}/permissions/expand
+```
 
 | Required | Argument          | Type   | Default | Description                                                                                                                                                                |
 |----------|-------------------|--------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|

docs/docs/api-overview/permission/lookup-entity.md

@@ -18,7 +18,10 @@ So, we provide 2 separate endpoints for data filtering check request,
 
 In this endpoint you'll get directly the IDs' of the entities that are authorized in an array.
 
-**POST** /v1/permissions/lookup-entity
+**Path** 
+```javascript
+ POST /v1/permissions/lookup-entity
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Permission/permissions.lookupEntity)
 
@@ -27,6 +30,7 @@ In this endpoint you'll get directly the IDs' of the entities that are authorize
 | [x]      | tenant_id         | string | -       | identifier of the tenant, if you are not using multi-tenancy (have only one tenant) use pre-inserted tenant `t1` for this field.                                           |
 | [ ]      | schema_version    | string | 8       | Version of the schema                                                                                                                                                      |
 | [ ]      | snap_token        | string | -       | the snap token to avoid stale cache, see more details on [Snap Tokens](../../../reference/snap-tokens)                                                                        |
+| [x]      | depth             | integer | 8       | Timeout limit when if recursive database queries got in loop                                                                                                                 |
 | [x]      | entity_type       | object | -       | type of the  entity. Example: repository”.                                                                                                                                 |
 | [x]      | permission        | string | -       | the action the user wants to perform on the resource                                                                                                                       |
 | [x]      | subject           | object | -       | the user or user set who wants to take the action. It contains type and id of the subject.                                                                                 |
@@ -137,14 +141,18 @@ Then queries each of them with `user:1.`
 
 The difference between this endpoint from direct Lookup Entity is response of this entity gives the IDs' as stream. This could be useful if you have large data set that getting all of the authorized data can take long with direct lookup entity endpoint.
 
-**POST** /v1/permissions/lookup-entity-stream
+**Path** 
+```javascript
+ POST /v1/permissions/lookup-entity-stream
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Permission/permissions.lookupEntityStream)
 
 | Required | Argument          | Type   | Default | Description                                                                                                                                                                |
 |----------|-------------------|--------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | [ ]      | schema_version    | string | 8       | Version of the schema                                                                                                                                                      |
 | [ ]      | snap_token        | string | -       | the snap token to avoid stale cache, see more details on [Snap Tokens](../../reference/snap-tokens.md)                                                                        |
+| [x]      | depth             | integer | 8       | Timeout limit when if recursive database queries got in loop                                                                                                                 |
 | [x]      | entity_type       | object | -       | type of the  entity. Example: repository”.                                                                                                                                 |
 | [x]      | permission        | string | -       | the action the user wants to perform on the resource                                                                                                                       |
 | [x]      | subject           | object | -       | the user or user set who wants to take the action. It contains type and id of the subject.                                                                                 |

docs/docs/api-overview/permission/lookup-subject.md

@@ -17,14 +17,18 @@ So, we provide 1 endpoint for subject filtering request,
 
 In this endpoint you'll get directly the IDs' of the subjects that are authorized in an array.
 
-**POST** /v1/permissions/lookup-subject
+**POST** 
+```javascript
+/v1/permissions/lookup-subject
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Permission/permissions.lookupSubject)
 
 | Required | Argument            | Type     | Default | Description                                                                                                                                                                |
 |----------|---------------------|----------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | [x]      | tenant_id           | string   | -       | identifier of the tenant, if you are not using multi-tenancy (have only one tenant) use pre-inserted tenant `t1` for this field.                                           |
 | [ ]      | schema_version      | string   | -       | Version of the schema                                                                                                                                                      |
+| [x]      | depth             | integer | 8       | Timeout limit when if recursive database queries got in loop                                                                                                                 |
 | [ ]      | snap_token          | string   | -       | the snap token to avoid stale cache, see more details on [Snap Tokens](../../reference/snap-tokens.md).                                                                       |
 | [x]      | entity              | object   | -       | contains entity type and id of the entity. Example: repository:1                                                                                                           |
 | [x]      | permission          | string   | -       | the action the user wants to perform on the resource                                                                                                                       |
@@ -40,6 +44,7 @@ cr, err: = client.Permission.LookupSubject(context.Background(), &v1.PermissionL
     Metadata: &v1.PermissionLookupSubjectRequestMetadata{
         SnapToken: "",
         SchemaVersion: "",
+        Depth: 20,
     },
     Entity: &v1.Entity{
         Type: "document",
@@ -62,6 +67,7 @@ client.permission.lookupSubject({
     metadata: {
         snapToken: "",
         schemaVersion: ""
+        depth: 20,
     },
     Entity: {
         Type: "document",
@@ -87,6 +93,7 @@ curl --location --request POST 'localhost:3476/v1/tenants/{tenant_id}/permission
   "metadata":{
     "snap_token": "",
     "schema_version": ""
+    "depth": 20,
   },
   "entity": {
     type: "document",

docs/docs/api-overview/permission/subject-permission.md

@@ -17,7 +17,10 @@ In this endpoint, you'll receive a map of permissions and their statuses directl
 
 ## Request
 
-**Path:** POST /v1/permissions/subject-permission
+**Path:** 
+```javascript
+POST /v1/permissions/subject-permission
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Permission/permissions.subjectPermission)
 
@@ -28,7 +31,7 @@ In this endpoint, you'll receive a map of permissions and their statuses directl
 | [ ]      | snap_token        | string  | -       | the snap token to avoid stale cache, see more details on [Snap Tokens](../../reference/snap-tokens.md).                                                                                                |
 | [x]      | entity            | object  | -       | contains entity type and id of the entity. Example: repository:1.                                                                                                                                   |
 | [x]      | subject           | object  | -       | the user or user set who wants to take the action. It contains type and id of the subject.                                                                                                          |
-| [ ]      | depth             | integer | 8       | Timeout limit when if recursive database queries got in loop                                                                                                                                        |
+| [x]      | depth             | integer | 8       | Timeout limit when if recursive database queries got in loop                                                                                                                                        |
 | [ ]      | only_permission   | bool    | false   | By default, the endpoint returns both permissions and relations associated with the user and entity. However, when the "only_permission" parameter is set to true, it returns only the permissions. |                                                                                                               |
 | [ ]      | context | object  | -       | Contextual data that can be dynamically added to permission check requests. See details on [Contextual Data](../../reference/contextual-tuples.md)                        |
 

docs/docs/api-overview/schema/write-schema.md

@@ -19,7 +19,9 @@ Permify Schema needed to be send to API endpoint **/v1/schemas/write"** for conf
 
 ## Request
 
-**POST** /v1/tenants/{tenant_id}/schemas/write
+```javascript
+POST /v1/tenants/{tenant_id}/schemas/write
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Schema/schemas.write)
 

docs/docs/api-overview/tenancy/create-tenant.md

@@ -11,7 +11,9 @@ We have a pre-inserted tenant - **t1** - by default for the ones that don't use
 
 ## Request
 
-**POST /v1/tenants/create**
+```javascript
+POST /v1/tenants/create
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Tenancy/tenants.create)
 

docs/docs/api-overview/tenancy/delete-tenant.md

@@ -6,8 +6,9 @@ import TabItem from '@theme/TabItem';
 You can delete a tenant with following API.
 
 ## Request
-
-**DELETE /v1/tenants/{id}** 
+```javascript
+DELETE /v1/tenants/{id}
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Tenancy/tenants.delete)
 

docs/docs/api-overview/watch/watch-changes.md

@@ -70,7 +70,10 @@ service:
 
 ## Request
 
-**Path:** POST /v1/watch/watch
+**Path:**
+```javascript
+POST /v1/watch/watch
+```
 
 [![View in Swagger](http://jessemillar.github.io/view-in-swagger-button/button.svg)](https://permify.github.io/permify-swagger/#/Watch/watch.watch)