amend watch api docs

authzed/api/v1/core.proto

@@ -115,8 +115,9 @@ message ObjectReference {
   ];
 }
 
-// ZedToken is used to provide causality metadata between Write and Check
-// requests.
+// ZedToken represents a point in time, or a "revision" in SpiceDB.
+// It is used to provide causality metadata between Write and read requests (Check, ReadRelationships, LookupResources, LookupSubjects)
+// and can also be used to start watching for changes from a specific point in time.
 //
 // See the authzed.api.v1.Consistency message for more information.
 message ZedToken {

authzed/api/v1/permission_service.proto

@@ -399,6 +399,7 @@ message WriteRelationshipsRequest {
 }
 
 message WriteRelationshipsResponse {
+  // written_at is the revision at which the relationships were written or deleted.
   ZedToken written_at = 1;
 }
 

authzed/api/v1/watch_service.proto

@@ -34,7 +34,7 @@ enum WatchKind {
   WATCH_KIND_INCLUDE_CHECKPOINTS = 3;
 }
 
-// WatchRequest specifies what mutations to watch for, and an optional start snapshot for when to start
+// WatchRequest specifies what mutations to watch for, and an optional start point for when to start
 // watching.
 message WatchRequest {
   // optional_object_types is a filter of resource object types to watch for relationship changes.
@@ -59,9 +59,7 @@ message WatchRequest {
 
   // optional_start_cursor is the ZedToken holding the point-in-time at
   // which to start watching for changes.
-  // If not specified, the watch will begin at the current head revision
-  // of the datastore, returning any updates that occur after the caller
-  // makes the request.
+  // If not specified, the watch will start from the current SpiceDB revision time of the request ("head revision").
   // Note that if this cursor references a point-in-time containing data
   // that has been garbage collected, an error will be returned.
   ZedToken optional_start_cursor = 2;
@@ -74,16 +72,18 @@ message WatchRequest {
   repeated RelationshipFilter optional_relationship_filters = 3;
 
   // optional_update_kinds, if specified, indicates what kinds of mutations to include.
+  // If your SpiceDB instance is running behind a proxy that aborts idle connections,
+  // we recommend including Checkpoints to keep the stream alive even when there are no changes.
   repeated WatchKind optional_update_kinds = 4;
 }
 
-// WatchResponse contains all mutation events in ascending timestamp order,
-// from the requested start snapshot to a snapshot
-// encoded in the watch response. The client can use the snapshot to resume
-// watching where the previous watch response left off.
+// WatchResponse contains all mutation events in ascending timestamp order.
+// This excludes relationships that were deleted because they expired.
+// The response includes a field that can be used to resume
+// watching from that point.
 message WatchResponse {
   // updates are the RelationshipUpdate events that have occurred since the
-  // last watch response.
+  // call was made, or since the point in time specified by changes_through.
   repeated RelationshipUpdate updates = 1;
 
   // changes_through is the ZedToken that represents the point in time

docs/apidocs.swagger.json

@@ -974,7 +974,7 @@
         "parameters": [
           {
             "name": "body",
-            "description": "WatchRequest specifies what mutations to watch for, and an optional start snapshot for when to start\nwatching.",
+            "description": "WatchRequest specifies what mutations to watch for, and an optional start point for when to start\nwatching.",
             "in": "body",
             "required": true,
             "schema": {
@@ -1618,6 +1618,19 @@
       },
       "description": "DirectSubjectSet is a subject set which is simply a collection of subjects."
     },
+    "DownloadPermissionSetsResponse": {
+      "type": "object",
+      "properties": {
+        "files": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "$ref": "#/definitions/File"
+          },
+          "title": "files contains the list of downloadable files with their URLs"
+        }
+      }
+    },
     "ExpCaveat": {
       "type": "object",
       "properties": {
@@ -2119,6 +2132,19 @@
       },
       "description": "ExportBulkRelationshipsResponse is one page in a stream of relationship\ngroups that meet the criteria specified by the originating request. The\nserver will continue to stream back relationship groups as quickly as it can\nuntil all relationships have been transmitted back."
     },
+    "File": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "title": "name is the filename of the downloadable file"
+        },
+        "url": {
+          "type": "string",
+          "title": "url is the download URL for the file (typically a signed S3 URL)"
+        }
+      }
+    },
     "ImportBulkRelationshipsRequest": {
       "type": "object",
       "properties": {
@@ -2264,11 +2290,11 @@
         "optionalConcreteLimit": {
           "type": "integer",
           "format": "int64",
-          "description": "optional_concrete_limit, if non-zero, specifies the limit on the number of\n*concrete* (non-wildcard) subjects to return before the stream is closed on the\nserver side. With the default value of zero, the stream will continue resolving\nconcrete subjects until exhausted or the stream is closed due to the client or\na network issue.\n\nNOTE: Wildcard subjects (\"*\") have special treatment when cursors and limits are used. Because\nwildcards can apply to *any* concrete subjects, if a wildcard subject is found within the dataset,\na wildcard subject can be returned for *all* LookupSubjects calls, regardless of the cursor or\nlimit.\n\nFor example, if wildcards are requested, a wildcard subject exists, there is a specified limit\nof 10 concrete subjects, and at least 10 concrete subjects exist, the API will return 11 subjects\nin total: the 10 concrete + the wildcard\n\nFurthermore, if a wildcard has a set of exclusions generated by the dataset,\nthe exclusions *will respect the cursor* and only a *partial* set of exclusions will be returned\nfor each invocation of the API.\n\n***IT IS UP TO THE CALLER IN THIS CASE TO COMBINE THE EXCLUSIONS IF DESIRED***"
+          "description": "optional_concrete_limit is currently unimplemented for LookupSubjects\nand will return an error as of SpiceDB version 1.40.1. This will\nbe implemented in a future version of SpiceDB."
         },
         "optionalCursor": {
           "$ref": "#/definitions/v1.Cursor",
-          "description": "optional_cursor, if specified, indicates the cursor after which results should resume being returned.\nThe cursor can be found on the LookupSubjectsResponse object.\n\nNOTE: See above for notes about how cursors interact with wildcard subjects."
+          "description": "optional_cursor is currently unimplemented for LookupSubjects\nand will be ignored as of SpiceDB version 1.40.1. This will\nbe implemented in a future version of SpiceDB."
         },
         "wildcardOption": {
           "$ref": "#/definitions/WildcardOption",
@@ -3101,7 +3127,7 @@
         },
         "optionalStartCursor": {
           "$ref": "#/definitions/ZedToken",
-          "description": "optional_start_cursor is the ZedToken holding the point-in-time at\nwhich to start watching for changes.\nIf not specified, the watch will begin at the current head revision\nof the datastore, returning any updates that occur after the caller\nmakes the request.\nNote that if this cursor references a point-in-time containing data\nthat has been garbage collected, an error will be returned."
+          "description": "optional_start_cursor is the ZedToken holding the point-in-time at\nwhich to start watching for changes.\nIf not specified, the watch will start from the current SpiceDB revision time of the request (\"head revision\").\nNote that if this cursor references a point-in-time containing data\nthat has been garbage collected, an error will be returned."
         },
         "optionalRelationshipFilters": {
           "type": "array",
@@ -3116,10 +3142,10 @@
           "items": {
             "$ref": "#/definitions/WatchKind"
           },
-          "description": "optional_update_kinds, if specified, indicates what kinds of mutations to include."
+          "description": "optional_update_kinds, if specified, indicates what kinds of mutations to include.\nIf your SpiceDB instance is running behind a proxy that aborts idle connections,\nwe recommend including Checkpoints to keep the stream alive even when there are no changes."
         }
       },
-      "description": "WatchRequest specifies what mutations to watch for, and an optional start snapshot for when to start\nwatching."
+      "description": "WatchRequest specifies what mutations to watch for, and an optional start point for when to start\nwatching."
     },
     "WatchResponse": {
       "type": "object",
@@ -3130,7 +3156,7 @@
             "type": "object",
             "$ref": "#/definitions/RelationshipUpdate"
           },
-          "description": "updates are the RelationshipUpdate events that have occurred since the\nlast watch response."
+          "description": "updates are the RelationshipUpdate events that have occurred since the\ncall was made, or since the point in time specified by changes_through."
         },
         "changesThrough": {
           "$ref": "#/definitions/ZedToken",
@@ -3149,7 +3175,7 @@
           "description": "is_checkpoint, if true, indicates that a checkpoint was reached.\nA checkpoint indicates that the server guarantees that the client\nwill not observe any changes at a revision below or equal to the revision in this response."
         }
       },
-      "description": "WatchResponse contains all mutation events in ascending timestamp order,\nfrom the requested start snapshot to a snapshot\nencoded in the watch response. The client can use the snapshot to resume\nwatching where the previous watch response left off."
+      "description": "WatchResponse contains all mutation events in ascending timestamp order.\nThis excludes relationships that were deleted because they expired.\nThe response includes a field that can be used to resume\nwatching from that point."
     },
     "WatchedPermission": {
       "type": "object",
@@ -3210,7 +3236,8 @@
       "type": "object",
       "properties": {
         "writtenAt": {
-          "$ref": "#/definitions/ZedToken"
+          "$ref": "#/definitions/ZedToken",
+          "description": "written_at is the revision at which the relationships were written or deleted."
         }
       }
     },
@@ -3241,7 +3268,7 @@
           "type": "string"
         }
       },
-      "description": "ZedToken is used to provide causality metadata between Write and Check\nrequests.\n\nSee the authzed.api.v1.Consistency message for more information."
+      "description": "ZedToken represents a point in time, or a \"revision\" in SpiceDB.\nIt is used to provide causality metadata between Write and read requests (Check, ReadRelationships, LookupResources, LookupSubjects)\nand can also be used to start watching for changes from a specific point in time.\n\nSee the authzed.api.v1.Consistency message for more information."
     },
     "v0.Cursor": {
       "type": "object",