add example to batch check description

openfga · Oct 14, 2024 · 48ad339 · 48ad339
1 parent fa1f791
commit 48ad339
Show file tree

Hide file tree

Showing 3 changed files with 1,076 additions and 953 deletions.
diff --git a/docs/openapiv2/apidocs.swagger.json b/docs/openapiv2/apidocs.swagger.json
diff --git a/openfga/v1/openfga_service.proto b/openfga/v1/openfga_service.proto
@@ -340,12 +340,57 @@ service OpenFGAService {
       description:
         "The `BatchCheck` API functions nearly identically to `Check`, but instead of checking a single "
         "user-object relationship BatchCheck accepts a list of relationships to check and returns a list containing a response "
-        "for each check it received.\n\n"
+        "for each check it received. Within each `BatchCheckItem`, this endpoint requires a `correlation_id` in the format "
+        "of a uuid for use in mapping the check results to the original item which was checked.\n\n"
         "Like `Check`, you can specify `contextual_tuples` and `context` with each individual tuple to be checked. Unlike check, however, "
         "`BatchCheck` also accepts `contextual_tuples` and `context` at the request level. If `contextual_tuples` or `context` are received "
         "at the request level, those contexts will taken into account when evaluating each check in the batch. If an individual check within the batch "
         "has its own `contextual_tuples` or `context`, **they will override** the request-level values and the request-level values will not be considered for that check.\n\n"
-        "For more details on how `Check` functions, see the docs for `/check`."
+        "For more details on how `Check` functions, see the docs for `/check`.\n\n"
+        "### Examples\n"
+        "#### A BatchCheckRequest\n"
+        "```json\n"
+        "{\n"
+        "  \"checks\": [\n"
+        "     {\n"
+        "       \"tuple_key\": {\n"
+        "         \"object\": \"document:2021-budget\"\n"
+        "         \"relation\": \"reader\",\n"
+        "         \"user\": \"user:anne\",\n"
+        "       },\n"
+        "       \"contextual_tuples\": {...}\n"
+        "       \"context\": {}\n"
+        "       \"correlation_id\": \"6c6b6603-d215-4d4f-b692-a3d6b20fe27f\"\n"
+        "     },\n"
+        "     {\n"
+        "       \"tuple_key\": {\n"
+        "         \"object\": \"document:2021-budget\"\n"
+        "         \"relation\": \"reader\",\n"
+        "         \"user\": \"user:bob\",\n"
+        "       },\n"
+        "       \"contextual_tuples\": {...}\n"
+        "       \"context\": {}\n"
+        "       \"correlation_id\": \"a289a9c0-a5ef-4d1e-ba06-fbe0cc1cbfdf\"\n"
+        "     },\n"
+        "   ]\n"
+        "}\n"
+        "```\n\n"
+        "Below is a possible response to the above request. Note that the result map's keys are the UUIDs from the checked items in the request:\n"
+        "```json\n"
+        "{\n"
+        "   \"result\": {\n"
+        "     \"a289a9c0-a5ef-4d1e-ba06-fbe0cc1cbfdf\": {\n"
+        "       \"allowed\": false, \n"
+        "       \"error\": {\"message\": \"\"}, \n"
+        "       \"query_duration_ms\": 5\n"
+        "    },\n"
+        "     \"6c6b6603-d215-4d4f-b692-a3d6b20fe27f\": {\n"
+        "       \"allowed\": true, \n"
+        "       \"error\": {\"message\": \"\"}, \n"
+        "       \"query_duration_ms\": 3\n"
+        "    }\n"
+        "}\n"
+        "```\n"
     };
   }