feat: refactor method to execute api method

Author: SoulPancake

README.md

@@ -1263,14 +1263,16 @@ response = await fga_client.write_assertions(body, options)
 
 ### Calling Other Endpoints
 
-In certain cases you may want to call other APIs not yet wrapped by the SDK. You can do so by using the `raw_request` method available on the `OpenFgaClient`. The `raw_request` method allows you to make raw HTTP calls to any OpenFGA endpoint by specifying the operation name, HTTP method, path, parameters, body, and headers, while still honoring the client configuration (authentication, telemetry, retries, and error handling).
+In certain cases you may want to call other APIs not yet wrapped by the SDK. You can do so by using the `execute_api_request` method available on the `OpenFgaClient`. The `execute_api_request` method allows you to make raw HTTP calls to any OpenFGA endpoint by specifying the HTTP method, path, body, query parameters, and path parameters, while still honoring the client configuration (authentication, telemetry, retries, and error handling).
+
+For streaming endpoints, use `execute_streamed_api_request` instead.
 
 This is useful when:
 - You want to call a new endpoint that is not yet supported by the SDK
 - You are using an earlier version of the SDK that doesn't yet support a particular endpoint
 - You have a custom endpoint deployed that extends the OpenFGA API
 
-In all cases, you initialize the SDK the same way as usual, and then call `raw_request` on the `fga_client` instance.
+In all cases, you initialize the SDK the same way as usual, and then call `execute_api_request` on the `fga_client` instance.
 
 ```python
 from openfga_sdk import ClientConfiguration, OpenFgaClient
@@ -1287,82 +1289,57 @@ async with OpenFgaClient(configuration) as fga_client:
         "resource": "resource:123",
     }
 
-    response = await fga_client.raw_request(
-        operation_name="CustomEndpoint",
-        method="POST",
-        path="/stores/{store_id}/custom-endpoint",
-        path_params={"store_id": FGA_STORE_ID},
-        query_params={"page_size": "20"},
-        body=request_body,
-        headers={"X-Experimental-Feature": "enabled"},
-    )
+    response = await fga_client.execute_api_request({
+        "operation_name": "CustomEndpoint",
+        "method": "POST",
+        "path": "/stores/{store_id}/custom-endpoint",
+        "path_params": {"store_id": FGA_STORE_ID},
+        "query_params": {"page_size": "20"},
+        "body": request_body,
+        "headers": {"X-Experimental-Feature": "enabled"},
+    })
 ```
 
-#### Example: Calling a new "Custom Endpoint" endpoint and handling raw response
+#### Example: Calling a custom endpoint with POST
 
 ```python
-# Get raw response without automatic decoding
-raw_response = await fga_client.raw_request(
-    operation_name="CustomEndpoint",
-    method="POST",
-    path="/stores/{store_id}/custom-endpoint",
-    path_params={"store_id": FGA_STORE_ID},
-    body={"user": "user:bob", "action": "custom_action"},
-)
+# Call a custom endpoint using path parameters
+response = await fga_client.execute_api_request({
+    "operation_name": "CustomEndpoint",        # For telemetry/logging
+    "method": "POST",
+    "path": "/stores/{store_id}/custom-endpoint",
+    "path_params": {"store_id": FGA_STORE_ID},
+    "body": {
+        "user": "user:bob",
+        "action": "custom_action",
+        "resource": "resource:123",
+    },
+    "query_params": {
+        "page_size": 20,
+    },
+})
 
 # Access the response data
-if raw_response.status == 200:
-    # Manually decode the response
-    result = raw_response.json()
-    if result:
-        print(f"Response: {result}")
-    
-    # You can access fields like headers, status code, etc. from raw_response:
-    print(f"Status Code: {raw_response.status}")
-    print(f"Headers: {raw_response.headers}")
-    print(f"Body as text: {raw_response.text()}")
-```
-
-#### Example: Calling a new "Custom Endpoint" endpoint and decoding response into a dictionary
-
-```python
-# Get raw response decoded into a dictionary
-response = await fga_client.raw_request(
-    operation_name="CustomEndpoint",
-    method="POST",
-    path="/stores/{store_id}/custom-endpoint",
-    path_params={"store_id": FGA_STORE_ID},
-    body={"user": "user:bob", "action": "custom_action"},
-)
-
-# The response body is automatically parsed as JSON if possible
-result = response.json()  # Returns dict or None if not JSON
-
-if result:
+if response.status == 200:
+    result = response.json()
     print(f"Response: {result}")
-    # Access fields from the decoded response
-    if "allowed" in result:
-        print(f"Allowed: {result['allowed']}")
-
-print(f"Status Code: {response.status}")
-print(f"Headers: {response.headers}")
 ```
 
 #### Example: Calling an existing endpoint with GET
 
 ```python
 # Get a list of stores with query parameters
-response = await fga_client.raw_request(
-    operation_name="ListStores",  # Required: descriptive name for the operation
-    method="GET",
-    path="/stores",
-    query_params={
+stores_response = await fga_client.execute_api_request({
+    "operation_name": "ListStores",
+    "method": "GET",
+    "path": "/stores",
+    "query_params": {
         "page_size": 10,
         "continuation_token": "eyJwayI6...",
     },
-)
+})
 
-stores = response.json()
+stores = stores_response.json()
 print("Stores:", stores)
 ```
 
@@ -1372,25 +1349,25 @@ Path parameters are specified in the path using `{param_name}` syntax and are re
 
 ```python
 # Using explicit path parameters
-response = await fga_client.raw_request(
-    operation_name="ReadAuthorizationModel",  # Required: descriptive name for the operation
-    method="GET",
-    path="/stores/{store_id}/authorization-models/{model_id}",
-    path_params={
+response = await fga_client.execute_api_request({
+    "operation_name": "GetAuthorizationModel",
+    "method": "GET",
+    "path": "/stores/{store_id}/authorization-models/{model_id}",
+    "path_params": {
         "store_id": "your-store-id",
         "model_id": "your-model-id",
     },
-)
+})
 
 # Using automatic store_id substitution
-response = await fga_client.raw_request(
-    operation_name="ReadAuthorizationModel",  # Required: descriptive name for the operation
-    method="GET",
-    path="/stores/{store_id}/authorization-models/{model_id}",
-    path_params={
+response = await fga_client.execute_api_request({
+    "operation_name": "GetAuthorizationModel",
+    "method": "GET",
+    "path": "/stores/{store_id}/authorization-models/{model_id}",
+    "path_params": {
         "model_id": "your-model-id",
     },
-)
+})
 ```
 
 ### Retries

openfga_sdk/client/client.py

@@ -1107,47 +1107,89 @@ def map_to_assertion(client_assertion: ClientAssertion):
         return api_response
 
     #######################
-    # Raw Request
+    # Execute API Request
     #######################
-    async def raw_request(
+    async def execute_api_request(
         self,
-        method: str,
-        path: str,
-        query_params: dict[str, str | int | list[str | int]] | None = None,
-        path_params: dict[str, str] | None = None,
-        headers: dict[str, str] | None = None,
-        body: dict[str, Any] | list[Any] | str | bytes | None = None,
-        operation_name: str | None = None,
+        request: dict[str, Any],
         options: dict[str, int | str | dict[str, int | str]] | None = None,
     ) -> RawResponse:
         """
-        Make a raw HTTP request to any OpenFGA API endpoint.
+        Execute an arbitrary HTTP request to any OpenFGA API endpoint.
 
-        :param method: HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)
-        :param path: API endpoint path (e.g., "/stores/{store_id}/check" or "/stores")
-        :param query_params: Optional query parameters as a dictionary
-        :param path_params: Optional path parameters to replace placeholders in path
-            (e.g., {"store_id": "abc", "model_id": "xyz"})
-        :param headers: Optional request headers (will be merged with default headers)
-        :param body: Optional request body (dict/list will be JSON serialized, str/bytes sent as-is)
-        :param operation_name: Required operation name for telemetry/logging (e.g., "Check", "Write", "CustomEndpoint")
+        Useful when you need to call a new or experimental API that doesn't yet have a built-in method in the SDK.
+        You still get the benefits of the SDK, like authentication, configuration, and consistent error handling.
+
+        :param request: Request parameters dict with the following keys:
+            - operation_name (str): Required. Operation name for telemetry and logging (e.g., "CustomCheck", "CustomEndpoint")
+            - method (str): Required. HTTP method (GET, POST, PUT, DELETE, PATCH)
+            - path (str): Required. API path (e.g., "/stores/{store_id}/my-endpoint")
+            - path_params (dict[str, str], optional): Path parameters to replace template variables in the path
+            - body (dict/list/str/bytes, optional): Request body for POST/PUT/PATCH requests
+            - query_params (dict[str, ...], optional): Query parameters
+            - headers (dict[str, str], optional): Custom request headers
         :param options: Optional request options:
-            - headers: Additional headers (merged with headers parameter)
+            - headers: Additional headers (merged with request['headers']; options['headers'] takes precedence)
             - retry_params: Override retry parameters for this request
-            - authorization_model_id: Not used in raw_request, but kept for consistency
         :return: RawResponse object with status, headers, and body
-        :raises FgaValidationException: If path contains {store_id} but store_id is not configured
+        :raises FgaValidationException: If required parameters are missing or invalid
+        :raises ApiException: For HTTP errors (with SDK error handling applied)
+        """
+        return await self._execute_api_request_internal(
+            request, options, streaming=False
+        )
+
+    async def execute_streamed_api_request(
+        self,
+        request: dict[str, Any],
+        options: dict[str, int | str | dict[str, int | str]] | None = None,
+    ) -> RawResponse:
+        """
+        Execute an arbitrary HTTP request to a streaming OpenFGA API endpoint.
+
+        Similar to execute_api_request but for streaming endpoints.
+
+        :param request: Request parameters dict (see execute_api_request for details)
+        :param options: Optional request options (see execute_api_request for details)
+        :return: RawResponse object with status, headers, and body
+        :raises FgaValidationException: If required parameters are missing or invalid
         :raises ApiException: For HTTP errors (with SDK error handling applied)
         """
+        return await self._execute_api_request_internal(
+            request, options, streaming=True
+        )
+
+    async def _execute_api_request_internal(
+        self,
+        request: dict[str, Any],
+        options: dict[str, int | str | dict[str, int | str]] | None = None,
+        streaming: bool = False,
+    ) -> RawResponse:
+        """Internal implementation for execute_api_request and execute_streamed_api_request."""
+        # Extract request parameters
+        operation_name = request.get("operation_name")
+        method = request.get("method")
+        path = request.get("path")
+        query_params = request.get("query_params")
+        path_params = request.get("path_params")
+        headers = request.get("headers")
+        body = request.get("body")
+
+        # Validate required parameters
+        if not operation_name:
+            raise FgaValidationException(
+                "operation_name is required for execute_api_request"
+            )
+        if not method:
+            raise FgaValidationException("method is required for execute_api_request")
+        if not path:
+            raise FgaValidationException("path is required for execute_api_request")
 
         request_headers = dict(headers) if headers else {}
         if options and options.get("headers"):
             if isinstance(options["headers"], dict):
                 request_headers.update(options["headers"])
 
-        if not operation_name:
-            raise FgaValidationException("operation_name is required for raw_request")
-
         resource_path = path
         path_params_dict = dict(path_params) if path_params else {}
 

openfga_sdk/sync/client/client.py

@@ -1105,47 +1105,85 @@ def map_to_assertion(client_assertion: ClientAssertion) -> Assertion:
         return api_response
 
     #######################
-    # Raw Request
+    # Execute API Request
     #######################
-    def raw_request(
+    def execute_api_request(
         self,
-        method: str,
-        path: str,
-        query_params: dict[str, str | int | list[str | int]] | None = None,
-        path_params: dict[str, str] | None = None,
-        headers: dict[str, str] | None = None,
-        body: dict[str, Any] | list[Any] | str | bytes | None = None,
-        operation_name: str | None = None,
+        request: dict[str, Any],
         options: dict[str, int | str | dict[str, int | str]] | None = None,
     ) -> RawResponse:
         """
-        Make a raw HTTP request to any OpenFGA API endpoint.
+        Execute an arbitrary HTTP request to any OpenFGA API endpoint.
 
-        :param method: HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)
-        :param path: API endpoint path (e.g., "/stores/{store_id}/check" or "/stores")
-        :param query_params: Optional query parameters as a dictionary
-        :param path_params: Optional path parameters to replace placeholders in path
-            (e.g., {"store_id": "abc", "model_id": "xyz"})
-        :param headers: Optional request headers (will be merged with default headers)
-        :param body: Optional request body (dict/list will be JSON serialized, str/bytes sent as-is)
-        :param operation_name: Required operation name for telemetry/logging (e.g., "Check", "Write", "CustomEndpoint")
+        Useful when you need to call a new or experimental API that doesn't yet have a built-in method in the SDK.
+        You still get the benefits of the SDK, like authentication, configuration, and consistent error handling.
+
+        :param request: Request parameters dict with the following keys:
+            - operation_name (str): Required. Operation name for telemetry and logging (e.g., "CustomCheck", "CustomEndpoint")
+            - method (str): Required. HTTP method (GET, POST, PUT, DELETE, PATCH)
+            - path (str): Required. API path (e.g., "/stores/{store_id}/my-endpoint")
+            - path_params (dict[str, str], optional): Path parameters to replace template variables in the path
+            - body (dict/list/str/bytes, optional): Request body for POST/PUT/PATCH requests
+            - query_params (dict[str, ...], optional): Query parameters
+            - headers (dict[str, str], optional): Custom request headers
         :param options: Optional request options:
-            - headers: Additional headers (merged with headers parameter)
+            - headers: Additional headers (merged with request['headers']; options['headers'] takes precedence)
             - retry_params: Override retry parameters for this request
-            - authorization_model_id: Not used in raw_request, but kept for consistency
         :return: RawResponse object with status, headers, and body
-        :raises FgaValidationException: If path contains {store_id} but store_id is not configured
+        :raises FgaValidationException: If required parameters are missing or invalid
+        :raises ApiException: For HTTP errors (with SDK error handling applied)
+        """
+        return self._execute_api_request_internal(request, options, streaming=False)
+
+    def execute_streamed_api_request(
+        self,
+        request: dict[str, Any],
+        options: dict[str, int | str | dict[str, int | str]] | None = None,
+    ) -> RawResponse:
+        """
+        Execute an arbitrary HTTP request to a streaming OpenFGA API endpoint.
+
+        Similar to execute_api_request but for streaming endpoints.
+
+        :param request: Request parameters dict (see execute_api_request for details)
+        :param options: Optional request options (see execute_api_request for details)
+        :return: RawResponse object with status, headers, and body
+        :raises FgaValidationException: If required parameters are missing or invalid
         :raises ApiException: For HTTP errors (with SDK error handling applied)
         """
+        return self._execute_api_request_internal(request, options, streaming=True)
+
+    def _execute_api_request_internal(
+        self,
+        request: dict[str, Any],
+        options: dict[str, int | str | dict[str, int | str]] | None = None,
+        streaming: bool = False,
+    ) -> RawResponse:
+        """Internal implementation for execute_api_request and execute_streamed_api_request."""
+        # Extract request parameters
+        operation_name = request.get("operation_name")
+        method = request.get("method")
+        path = request.get("path")
+        query_params = request.get("query_params")
+        path_params = request.get("path_params")
+        headers = request.get("headers")
+        body = request.get("body")
+
+        # Validate required parameters
+        if not operation_name:
+            raise FgaValidationException(
+                "operation_name is required for execute_api_request"
+            )
+        if not method:
+            raise FgaValidationException("method is required for execute_api_request")
+        if not path:
+            raise FgaValidationException("path is required for execute_api_request")
 
         request_headers = dict(headers) if headers else {}
         if options and options.get("headers"):
             if isinstance(options["headers"], dict):
                 request_headers.update(options["headers"])
 
-        if not operation_name:
-            raise FgaValidationException("operation_name is required for raw_request")
-
         resource_path = path
         path_params_dict = dict(path_params) if path_params else {}