Watch API

POST

tenants

{tenant_id}

watch

cr, err := client.Watch.Watch(context.Background(), &v1.WatchRequest{
    TenantId:  "t1",
    SnapToken: "",
})
// handle stream response
for {
    res, err := cr.Recv()

    if err == io.EOF {
        break
    }

    // res.Changes
}

{
  "result": {
    "changes": {
      "snap_token": "<string>",
      "data_changes": [
        {
          "operation": "OPERATION_UNSPECIFIED",
          "tuple": {
            "entity": {
              "type": "<string>",
              "id": "<string>"
            },
            "relation": "<string>",
            "subject": {
              "type": "<string>",
              "id": "<string>",
              "relation": "<string>"
            }
          },
          "attribute": {
            "entity": {
              "type": "<string>",
              "id": "<string>"
            },
            "attribute": "<string>",
            "value": {
              "@type": "<string>"
            }
          }
        }
      ]
    }
  },
  "error": {
    "code": 123,
    "message": "<string>",
    "details": [
      {
        "@type": "<string>"
      }
    ]
  }
}

The Permify Watch API acts as a real-time broadcaster that shows changes in the relation tuples.

The Watch API exclusively supports gRPC and works with PostgreSQL, given the track_commit_timestamp option is enabled. Please note, it doesn’t support in-memory databases or HTTP communication.

Requirements

PostgreSQL database set up with track_commit_timestamp option enabled

Enabling track_commit_timestamp on PostgreSQL

To ensure data consistency and synchronization between your application and Permify, enable track_commit_timestamp on your PostgreSQL server. This can be done by executing the following options in your PostgreSQL:

Option 1: SQL Command

Open your PostgreSQL command line interface.

Execute the following command:

ALTER SYSTEM SET track_commit_timestamp = ON;

Reload the configuration with the following command:
```
SELECT pg_reload_conf();
```

Option 2: Editing postgresql.conf

Find and open the postgresql.conf file in a text editor. Its location depends on your PostgreSQL installation. Common locations are:
- Debian-based systems: /etc/postgresql/[version]/main/postgresql.conf
- Red Hat-based systems: /var/lib/pgsql/data/postgresql.conf
Add or modify the following line in the postgresql.conf file:
```
track_commit_timestamp = on
```
Save and close the postgresql.conf file.
Reload the PostgreSQL configuration for the changes to take effect. This can be done via the PostgreSQL console:
```
SELECT pg_reload_conf();
```
Or if you have command line access, use:
```
sudo service postgresql reload
```

Please ensure you have the necessary permissions to execute these commands or modify the postgresql.conf file. Also, remember that changes in the postgresql.conf file will persist across restarts, while the SQL method may need to be reapplied depending on your PostgreSQL version and setup.

Important Configuration Requirement: To use the Watch API, it must be enabled in your configuration file. Add or modify the following lines:

service:
  watch:
    enabled: true

Path Parameters

tenant_id

string

required

Identifier of the tenant, if you are not using multi-tenancy (have only one tenant) use pre-inserted tenant <code>t1</code> for this field. Required, and must match the pattern \“[a-zA-Z0-9-,]+\“, max 64 bytes.

Body

application/json

snap_token

string

The snap token to avoid stale cache, see more details on Snap Tokens.

Response

200 - application/json

result

object

WatchResponse is the response message for the Watch RPC. It contains the changes in the data that are being watched.

result.changes

object

DataChanges represent changes in data with a snap token and a list of data change objects.

result.changes.snap_token

string

The snapshot token.

result.changes.data_changes

object[]

The list of data changes.

result.changes.data_changes.operation

enum<string>

default: OPERATION_UNSPECIFIED

OPERATION_UNSPECIFIED: Default operation, not specified.
OPERATION_CREATE: Creation operation.
OPERATION_DELETE: Deletion operation.

Available options:

OPERATION_UNSPECIFIED,

OPERATION_CREATE,

OPERATION_DELETE

result.changes.data_changes.tuple

object

Tuple is a structure that includes an entity, a relation, and a subject.

result.changes.data_changes.attribute

object

Attribute represents an attribute of an entity with a specific type and value.

result.changes.data_changes.attribute.entity

object

Entity represents an entity with a type and an identifier.

result.changes.data_changes.attribute.attribute

string

result.changes.data_changes.attribute.value

object

Any contains an arbitrary serialized protocol buffer message along with a URL that describes the type of the serialized message.

Protobuf library provides support to pack/unpack Any values in the form of utility functions or additional generated methods of the Any type.

Example 1: Pack and unpack a message in C++.

Foo foo = ...;
Any any;
any.PackFrom(foo);
...
if (any.UnpackTo(&foo)) {
  ...
}

Example 2: Pack and unpack a message in Java.

Foo foo = ...;
Any any = Any.pack(foo);
...
if (any.is(Foo.class)) {
  foo = any.unpack(Foo.class);
}

Example 3: Pack and unpack a message in Python.

foo = Foo(...)
any = Any()
any.Pack(foo)
...
if any.Is(Foo.DESCRIPTOR):
  any.Unpack(foo)
  ...

Example 4: Pack and unpack a message in Go

 foo := &pb.Foo{...}
 any, err := anypb.New(foo)
 if err != nil {
   ...
 }
 ...
 foo := &pb.Foo{}
 if err := any.UnmarshalTo(foo); err != nil {
   ...
 }

The pack methods provided by protobuf library will by default use 'type.googleapis.com/full.type.name' as the type URL and the unpack methods only use the fully qualified type name after the last '/' in the type URL, for example "foo.bar.com/x/y.z" will yield type name "y.z".

JSON

The JSON representation of an Any value uses the regular representation of the deserialized, embedded message, with an additional field @type which contains the type URL. Example:

package google.profile;
message Person {
  string first_name = 1;
  string last_name = 2;
}

{
  "@type": "type.googleapis.com/google.profile.Person",
  "firstName": <string>,
  "lastName": <string>
}

If the embedded message type is well-known and has a custom JSON representation, that representation will be embedded adding a field value which holds the custom JSON in addition to the @type field. Example (for message [google.protobuf.Duration][]):

{
  "@type": "type.googleapis.com/google.protobuf.Duration",
  "value": "1.212s"
}

error

object

Delete Bundle

cr, err := client.Watch.Watch(context.Background(), &v1.WatchRequest{
    TenantId:  "t1",
    SnapToken: "",
})
// handle stream response
for {
    res, err := cr.Recv()

    if err == io.EOF {
        break
    }

    // res.Changes
}

{
  "result": {
    "changes": {
      "snap_token": "<string>",
      "data_changes": [
        {
          "operation": "OPERATION_UNSPECIFIED",
          "tuple": {
            "entity": {
              "type": "<string>",
              "id": "<string>"
            },
            "relation": "<string>",
            "subject": {
              "type": "<string>",
              "id": "<string>",
              "relation": "<string>"
            }
          },
          "attribute": {
            "entity": {
              "type": "<string>",
              "id": "<string>"
            },
            "attribute": "<string>",
            "value": {
              "@type": "<string>"
            }
          }
        }
      ]
    }
  },
  "error": {
    "code": 123,
    "message": "<string>",
    "details": [
      {
        "@type": "<string>"
      }
    ]
  }
}

API Documentation

Schema Service

Data Service

Permission Service

Tenancy Service

Bundle Service

Watch Service

Requirements

Enabling track_commit_timestamp on PostgreSQL

Option 1: SQL Command

Option 2: Editing postgresql.conf

Path Parameters

Body

Response

API Documentation

Schema Service

Data Service

Permission Service

Tenancy Service

Bundle Service

Watch Service

​Requirements

​Enabling track_commit_timestamp on PostgreSQL

​Option 1: SQL Command

​Option 2: Editing postgresql.conf

Path Parameters

Body

Response

Requirements

Enabling track_commit_timestamp on PostgreSQL

Option 1: SQL Command

Option 2: Editing postgresql.conf