feat: Add description documentation for consistency in Check and List…

…Objects

openfga/v1/openfga_service.proto

@@ -211,6 +211,7 @@ service OpenFGAService {
         "You may also provide an `authorization_model_id` in the body. This will be used to assert that the input `tuple_key` is valid for the model specified. "
         "If not specified, the assertion will be made against the latest authorization model ID. It is strongly recommended to specify authorization model id for better performance.\n"
         "You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n"
+        "By default, the Check API caches results for a short time to optimize performance. You may specify a value of `HIGHER_CONSISTENCY` for the optional `consistency` parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency.\n"
         "The response will return whether the relationship exists in the field `allowed`.\n\n"
         "Some exceptions apply, but in general, if a Check API responds with `{allowed: true}`, then you can expect the equivalent ListObjects query to return the object, and viceversa. \n"
         "For example, if `Check(user:anne, reader, document:2021-budget)` responds with `{allowed: true}`, then `ListObjects(user:anne, reader, document)` may include `document:2021-budget` in the response.\n"
@@ -309,6 +310,18 @@ service OpenFGAService {
         "}\n"
         "```\n"
         "will return `{ \"allowed\": true }`, even though a specific user of the userset `group:finance#member` does not have the `reader` relationship with the given object.\n"
+        "### Requesting higher consistency\n"
+        "By default, the Check API caches results for a short time to optimize performance. You may request higher consistency to inform the server that higher consistency should be preferred at the expense of increased latency. Care should be taken when requesting higher consistency due to the increased latency.\n"
+        "```json\n"
+        "{\n"
+        "  \"tuple_key\": {\n"
+        "     \"user\": \"group:finance#member\",\n"
+        "     \"relation\": \"reader\",\n"
+        "     \"object\": \"document:2021-budget\"\n"
+        "  },\n"
+        "  \"consistency\": \"HIGHER_CONSISTENCY\"\n"
+        "}\n"
+        "```\n"
     };
   }
 
@@ -734,6 +747,7 @@ service OpenFGAService {
         "model ID will be used. It is strongly recommended to specify authorization model id for better performance.\n"
         "You may also specify `contextual_tuples` that will be treated as regular tuples. Each of these tuples may have an associated `condition`.\n"
         "You may also provide a `context` object that will be used to evaluate the conditioned tuples in the system. It is strongly recommended to provide a value for all the input parameters of all the conditions, to ensure that all tuples be evaluated correctly.\n"
+        "By default, the Check API caches results for a short time to optimize performance. You may specify a value of `HIGHER_CONSISTENCY` for the optional `consistency` parameter in the body to inform the server that higher conisistency is preferred at the expense of increased latency. Consideration should be given to the increased latency if requesting higher consistency.\n"
         "The response will contain the related objects in an array in the \"objects\" field of the response and they will "
         "be strings in the object format `<type>:<id>` (e.g. \"document:roadmap\").\n"
         "The number of objects in the response array will be limited by the execution timeout specified in the flag OPENFGA_LIST_OBJECTS_DEADLINE "