feat!: add support for BatchCheck API (#154)

Author: ewanharris

.openapi-generator/FILES

@@ -19,6 +19,11 @@ docs/Assertion.md
 docs/AssertionTupleKey.md
 docs/AuthErrorCode.md
 docs/AuthorizationModel.md
+docs/BatchCheckItem.md
+docs/BatchCheckRequest.md
+docs/BatchCheckResponse.md
+docs/BatchCheckSingleResult.md
+docs/CheckError.md
 docs/CheckRequest.md
 docs/CheckRequestTupleKey.md
 docs/CheckResponse.md
@@ -119,8 +124,12 @@ openfga_sdk/client/client.py
 openfga_sdk/client/configuration.py
 openfga_sdk/client/models/__init__.py
 openfga_sdk/client/models/assertion.py
+openfga_sdk/client/models/batch_check_item.py
+openfga_sdk/client/models/batch_check_request.py
 openfga_sdk/client/models/batch_check_response.py
+openfga_sdk/client/models/batch_check_single_response.py
 openfga_sdk/client/models/check_request.py
+openfga_sdk/client/models/client_batch_check_response.py
 openfga_sdk/client/models/expand_request.py
 openfga_sdk/client/models/list_objects_request.py
 openfga_sdk/client/models/list_relations_request.py
@@ -142,6 +151,11 @@ openfga_sdk/models/assertion.py
 openfga_sdk/models/assertion_tuple_key.py
 openfga_sdk/models/auth_error_code.py
 openfga_sdk/models/authorization_model.py
+openfga_sdk/models/batch_check_item.py
+openfga_sdk/models/batch_check_request.py
+openfga_sdk/models/batch_check_response.py
+openfga_sdk/models/batch_check_single_result.py
+openfga_sdk/models/check_error.py
 openfga_sdk/models/check_request.py
 openfga_sdk/models/check_request_tuple_key.py
 openfga_sdk/models/check_response.py

CHANGELOG.md

@@ -3,9 +3,17 @@
 ## [Unreleased](https://github.com/openfga/python-sdk/compare/v0.8.1...HEAD)
 
 - feat: remove client-side validation - thanks @GMorris-professional (#155)
-- feat: add support for `start_time` parameter in `ReadChanges` endpoint (#156)
+- feat: add support for `start_time` parameter in `ReadChanges` endpoint (#156) - Note, this feature requires v1.8.0 of OpenFGA or newer
+- feat!: add support for `BatchCheck` API (#154) - Note, this feature requires v1.8.2 of OpenFGA or newer
 - fix: change default max retry limit to 3 from 15 - thanks @ovindu-a (#155)
 
+BREAKING CHANGE:
+
+Usage of the existing batch_check should now use client_batch_check instead, additionally the existing
+BatchCheckResponse has been renamed to ClientBatchCheckClientResponse.
+
+Please see (#154)(https://github.com/openfga/python-sdk/pull/154) for more details on this change.
+
 ## v0.8.1
 
 ### [0.8.1](https://github.com/openfga/python-sdk/compare/v0.8.0...v0.8.1) (2024-11-26)

README.md

@@ -724,17 +724,19 @@ If 429s or 5xxs are encountered, the underlying check will retry up to 3 times b
 
 ```python
 # from openfga_sdk import OpenFgaClient
-# from openfga_sdk.client import ClientCheckRequest
-# from openfga_sdk.client.models import ClientTuple
-
+# from openfga_sdk.client.models import (
+#   ClientTuple,
+#   ClientBatchCheckItem,
+#   ClientBatchCheckRequest,
+# )
 # Initialize the fga_client
 # fga_client = OpenFgaClient(configuration)
 
 options = {
     # You can rely on the model id set in the configuration or override it for this specific request
     "authorization_model_id": "01GXSA8YR785C4FYS3C0RTG7B1"
 }
-body = [ClientCheckRequest(
+checks = [ClientBatchCheckItem(
     user="user:81684243-9356-4421-8fbf-a4f8d36aa31b",
     relation="viewer",
     object="document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
@@ -748,7 +750,7 @@ body = [ClientCheckRequest(
     context=dict(
         ViewCount=100
     )
-), ClientCheckRequest(
+), ClientBatchCheckItem(
     user="user:81684243-9356-4421-8fbf-a4f8d36aa31b",
     relation="admin",
     object="document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
@@ -759,20 +761,21 @@ body = [ClientCheckRequest(
             object="document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
         ),
     ]
-), ClientCheckRequest(
+), ClientBatchCheckItem(
     user="user:81684243-9356-4421-8fbf-a4f8d36aa31b",
     relation="creator",
     object="document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
-), ClientCheckRequest(
+), ClientBatchCheckItem(
     user="user:81684243-9356-4421-8fbf-a4f8d36aa31b",
     relation="deleter",
     object="document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
 )]
 
-response = await fga_client.batch_check(body, options)
-# response.responses = [{
+response = await fga_client.batch_check(ClientBatchCheckRequest(checks=checks), options)
+# response.result = [{
 #   allowed: false,
-#   request: {
+#   correlation_id: "de3630c2-f9be-4ee5-9441-cb1fbd82ce75",
+#   tuple: {
 #     user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
 #     relation: "viewer",
 #     object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
@@ -787,7 +790,8 @@ response = await fga_client.batch_check(body, options)
 #   }
 # }, {
 #   allowed: false,
-#   request: {
+#   correlation_id: "6d7c7129-9607-480e-bfd0-17c16e46b9ec",
+#   tuple: {
 #     user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
 #     relation: "admin",
 #     object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
@@ -799,14 +803,19 @@ response = await fga_client.batch_check(body, options)
 #   }
 # }, {
 #   allowed: false,
-#   request: {
+#   correlation_id: "210899b9-6bc3-4491-bdd1-d3d79780aa31",
+#   tuple: {
 #     user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
 #     relation: "creator",
 #     object: "document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a",
 #   },
-#   error: <FgaError ...>
+#   error: {
+#       input_error: "validation_error",
+#       message: "relation 'document#creator' not found"
+#   }
 # }, {
 #   allowed: true,
+#   correlation_id: "55cc1946-9fc3-4710-bd40-8fe2687ed8da",
 #   request: {
 #     user: "user:81684243-9356-4421-8fbf-a4f8d36aa31b",
 #     relation: "deleter",
@@ -1043,6 +1052,7 @@ async def main():
 
 Class | Method | HTTP request | Description
 ------------ | ------------- | ------------- | -------------
+*OpenFgaApi* | [**batch_check**](https://github.com/openfga/python-sdk/blob/main/docs/OpenFgaApi.md#batch_check) | **POST** /stores/{store_id}/batch-check | Send a list of &#x60;check&#x60; operations in a single request
 *OpenFgaApi* | [**check**](https://github.com/openfga/python-sdk/blob/main/docs/OpenFgaApi.md#check) | **POST** /stores/{store_id}/check | Check whether a user is authorized to access an object
 *OpenFgaApi* | [**create_store**](https://github.com/openfga/python-sdk/blob/main/docs/OpenFgaApi.md#create_store) | **POST** /stores | Create a store
 *OpenFgaApi* | [**delete_store**](https://github.com/openfga/python-sdk/blob/main/docs/OpenFgaApi.md#delete_store) | **DELETE** /stores/{store_id} | Delete a store
@@ -1072,6 +1082,11 @@ Class | Method | HTTP request | Description
  - [AssertionTupleKey](https://github.com/openfga/python-sdk/blob/main/docs/AssertionTupleKey.md)
  - [AuthErrorCode](https://github.com/openfga/python-sdk/blob/main/docs/AuthErrorCode.md)
  - [AuthorizationModel](https://github.com/openfga/python-sdk/blob/main/docs/AuthorizationModel.md)
+ - [BatchCheckItem](https://github.com/openfga/python-sdk/blob/main/docs/BatchCheckItem.md)
+ - [BatchCheckRequest](https://github.com/openfga/python-sdk/blob/main/docs/BatchCheckRequest.md)
+ - [BatchCheckResponse](https://github.com/openfga/python-sdk/blob/main/docs/BatchCheckResponse.md)
+ - [BatchCheckSingleResult](https://github.com/openfga/python-sdk/blob/main/docs/BatchCheckSingleResult.md)
+ - [CheckError](https://github.com/openfga/python-sdk/blob/main/docs/CheckError.md)
  - [CheckRequest](https://github.com/openfga/python-sdk/blob/main/docs/CheckRequest.md)
  - [CheckRequestTupleKey](https://github.com/openfga/python-sdk/blob/main/docs/CheckRequestTupleKey.md)
  - [CheckResponse](https://github.com/openfga/python-sdk/blob/main/docs/CheckResponse.md)

docs/BatchCheckItem.md

@@ -0,0 +1,14 @@
+# BatchCheckItem
+
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**tuple_key** | [**CheckRequestTupleKey**](CheckRequestTupleKey.md) |  | 
+**contextual_tuples** | [**ContextualTupleKeys**](ContextualTupleKeys.md) |  | [optional] 
+**context** | **object** |  | [optional] 
+**correlation_id** | **str** | correlation_id must be a string containing only letters, numbers, or hyphens, with length ≤ 36 characters. | 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+

docs/BatchCheckRequest.md

@@ -0,0 +1,13 @@
+# BatchCheckRequest
+
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**checks** | [**list[BatchCheckItem]**](BatchCheckItem.md) |  | 
+**authorization_model_id** | **str** |  | [optional] 
+**consistency** | [**ConsistencyPreference**](ConsistencyPreference.md) |  | [optional] 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+

docs/BatchCheckResponse.md

@@ -0,0 +1,11 @@
+# BatchCheckResponse
+
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**result** | [**dict[str, BatchCheckSingleResult]**](BatchCheckSingleResult.md) | map keys are the correlation_id values from the BatchCheckItems in the request | [optional] 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+

docs/BatchCheckSingleResult.md

@@ -0,0 +1,12 @@
+# BatchCheckSingleResult
+
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**allowed** | **bool** |  | [optional] 
+**error** | [**CheckError**](CheckError.md) |  | [optional] 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+

docs/CheckError.md

@@ -0,0 +1,13 @@
+# CheckError
+
+
+## Properties
+Name | Type | Description | Notes
+------------ | ------------- | ------------- | -------------
+**input_error** | [**ErrorCode**](ErrorCode.md) |  | [optional] 
+**internal_error** | [**InternalErrorCode**](InternalErrorCode.md) |  | [optional] 
+**message** | **str** |  | [optional] 
+
+[[Back to Model list]](../README.md#documentation-for-models) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to README]](../README.md)
+
+

docs/OpenFgaApi.md

@@ -4,6 +4,7 @@ All URIs are relative to *api.fga.example*
 
 Method | HTTP request | Description
 ------------- | ------------- | -------------
+[**batch_check**](OpenFgaApi.md#batch_check) | **POST** /stores/{store_id}/batch-check | Send a list of `check` operations in a single request
 [**check**](OpenFgaApi.md#check) | **POST** /stores/{store_id}/check | Check whether a user is authorized to access an object
 [**create_store**](OpenFgaApi.md#create_store) | **POST** /stores | Create a store
 [**delete_store**](OpenFgaApi.md#delete_store) | **DELETE** /stores/{store_id} | Delete a store
@@ -22,6 +23,90 @@ Method | HTTP request | Description
 [**write_authorization_model**](OpenFgaApi.md#write_authorization_model) | **POST** /stores/{store_id}/authorization-models | Create a new authorization model
 
 
+# **batch_check**
+> BatchCheckResponse batch_check(body)
+
+Send a list of `check` operations in a single request
+
+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 map containing `BatchCheckItem` response for each check it received.  An associated `correlation_id` is required for each check in the batch. This ID is used to correlate a check to the appropriate response. It is a string consisting of only alphanumeric characters or hyphens with a maximum length of 36 characters. This `correlation_id` is used to map the result of each check to the item which was checked, so it must be unique for each item in the batch. We recommend using a UUID or ULID as the `correlation_id`, but you can use whatever unique identifier you need as long  as it matches this regex pattern: `^[\\w\\d-]{1,36}$`  For more details on how `Check` functions, see the docs for `/check`.  ### Examples #### A BatchCheckRequest ```json {   \"checks\": [      {        \"tuple_key\": {          \"object\": \"document:2021-budget\"          \"relation\": \"reader\",          \"user\": \"user:anne\",        },        \"contextual_tuples\": {...}        \"context\": {}        \"correlation_id\": \"01JA8PM3QM7VBPGB8KMPK8SBD5\"      },      {        \"tuple_key\": {          \"object\": \"document:2021-budget\"          \"relation\": \"reader\",          \"user\": \"user:bob\",        },        \"contextual_tuples\": {...}        \"context\": {}        \"correlation_id\": \"01JA8PMM6A90NV5ET0F28CYSZQ\"      }    ] } ```  Below is a possible response to the above request. Note that the result map's keys are the `correlation_id` values from the checked items in the request: ```json {    \"result\": {      \"01JA8PMM6A90NV5ET0F28CYSZQ\": {        \"allowed\": false,         \"error\": {\"message\": \"\"}      },      \"01JA8PM3QM7VBPGB8KMPK8SBD5\": {        \"allowed\": true,         \"error\": {\"message\": \"\"}      } } ``` 
+
+### Example
+
+```python
+import time
+import openfga_sdk
+from openfga_sdk.rest import ApiException
+from pprint import pprint
+# To configure the configuration
+# host is mandatory
+# api_scheme is optional and default to https
+# store_id is mandatory
+# See configuration.py for a list of all supported configuration parameters.
+configuration = openfga_sdk.Configuration(
+    scheme = "https",
+    api_host = "api.fga.example",
+    store_id = 'YOUR_STORE_ID',
+)
+
+
+# When authenticating via the API TOKEN method
+credentials = Credentials(method='api_token', configuration=CredentialConfiguration(api_token='TOKEN1'))
+configuration = openfga_sdk.Configuration(
+    scheme = "https",
+    api_host = "api.fga.example",
+    store_id = 'YOUR_STORE_ID',
+    credentials = credentials
+)
+
+# Enter a context with an instance of the API client
+async with openfga_sdk.ApiClient(configuration) as api_client:
+    # Create an instance of the API class
+    api_instance = openfga_sdk.OpenFgaApi(api_client)
+    body = openfga_sdk.BatchCheckRequest() # BatchCheckRequest | 
+
+    try:
+        # Send a list of `check` operations in a single request
+        api_response = await api_instance.api_instance.batch_check(body)
+        pprint(api_response)
+    except ApiException as e:
+        print("Exception when calling OpenFgaApi->batch_check: %s\n" % e)
+    await api_client.close()
+```
+
+
+### Parameters
+
+Name | Type | Description  | Notes
+------------- | ------------- | ------------- | -------------
+ **body** | [**BatchCheckRequest**](BatchCheckRequest.md)|  |
+
+### Return type
+
+[**BatchCheckResponse**](BatchCheckResponse.md)
+
+### Authorization
+
+No authorization required
+
+### HTTP request headers
+
+ - **Content-Type**: application/json
+ - **Accept**: application/json
+
+### HTTP response details
+| Status code | Description | Response headers |
+|-------------|-------------|------------------|
+**200** | A successful response. |  -  |
+**400** | Request failed due to invalid input. |  -  |
+**401** | Not authenticated. |  -  |
+**403** | Forbidden. |  -  |
+**404** | Request failed due to incorrect path. |  -  |
+**409** | Request was aborted due a transaction conflict. |  -  |
+**422** | Request timed out due to excessive request throttling. |  -  |
+**500** | Request failed due to internal server error. |  -  |
+
+[[Back to top]](#) [[Back to API list]](../README.md#documentation-for-api-endpoints) [[Back to Model list]](../README.md#documentation-for-models) [[Back to README]](../README.md)
+
 # **check**
 > CheckResponse check(body)