feat: calling other endpoints section

Author: SoulPancake

README.md

@@ -46,7 +46,7 @@ This is an autogenerated Java SDK for OpenFGA. It provides a wrapper around the
     - [Assertions](#assertions)
       - [Read Assertions](#read-assertions)
       - [Write Assertions](#write-assertions)
-  - [Raw API](#raw-api)
+  - [Calling Other Endpoints](#calling-other-endpoints)
   - [Retries](#retries)
   - [API Endpoints](#api-endpoints)
   - [Models](#models)
@@ -1168,57 +1168,85 @@ try {
 }
 ```
 
-### Raw API
+### Calling Other Endpoints
 
-The Raw API allows execution of HTTP requests to OpenFGA endpoints using the SDK's configured HTTP client. This is useful for accessing API endpoints that do not yet have typed SDK method implementations.
+In certain cases you may want to call other APIs not yet wrapped by the SDK. You can do so by using the APIExecutor available from the `fgaClient`. The APIExecutor 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).
 
-#### Usage
+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
 
-```java
-import dev.openfga.sdk.api.client.OpenFgaClient;
-import dev.openfga.sdk.api.client.RawRequestBuilder;
-import dev.openfga.sdk.api.configuration.ClientConfiguration;
-import java.util.Map;
-
-// Response type
-class CustomResponse {
-    public boolean success;
-    public int count;
-}
+In all cases, you initialize the SDK the same way as usual, and then get the APIExecutor from the `fgaClient` instance.
 
-// Client configuration
+```java
+// Initialize the client, same as above
 ClientConfiguration config = new ClientConfiguration()
     .apiUrl("http://localhost:8080")
     .storeId("01YCP46JKYM8FJCQ37NMBYHE5X");
-OpenFgaClient client = new OpenFgaClient(config);
-
-// Request execution
-RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/endpoint")
-    .pathParam("store_id", client.getStoreId())
-    .queryParam("param", "value")
-    .body(Map.of("key", "value"));
-
-// Typed response
-client.raw().send(request, CustomResponse.class)
-    .thenAccept(response -> {
-        System.out.println("Status: " + response.getStatusCode());
-        System.out.println("Data: " + response.getData());
-    });
-
-// Raw JSON response
-client.raw().send(request)
-    .thenAccept(response -> {
-        System.out.println("JSON: " + response.getRawResponse());
-    });
+OpenFgaClient fgaClient = new OpenFgaClient(config);
+
+// Get the generic API executor
+APIExecutor executor = fgaClient.getAPIExecutor();
+
+// Custom new endpoint that doesn't exist in the SDK yet
+Map<String, Object> requestBody = Map.of(
+    "user", "user:bob",
+    "action", "custom_action",
+    "resource", "resource:123"
+);
+
+// Build the request
+APIExecutorRequest request = new APIExecutorRequestBuilder("CustomEndpoint", "POST", "/stores/{store_id}/custom-endpoint")
+    .withPathParameter("store_id", storeId)
+    .withQueryParameter("page_size", "20")
+    .withQueryParameter("continuation_token", "eyJwayI6...")
+    .withBody(requestBody)
+    .withHeader("X-Experimental-Feature", "enabled")
+    .build();
+```
+
+#### Example: Calling a new "Custom Endpoint" endpoint and handling raw response
+
+```java
+// Get raw response without automatic decoding
+APIExecutorResponse rawResponse = executor.execute(request).get();
+
+// Manually decode the response
+ObjectMapper mapper = new ObjectMapper();
+Map<String, Object> result = mapper.readValue(rawResponse.getBody(), new TypeReference<Map<String, Object>>() {});
+
+System.out.println("Response: " + result);
+
+// You can access fields like headers, status code, etc. from rawResponse:
+System.out.println("Status Code: " + rawResponse.getStatusCode());
+System.out.println("Headers: " + rawResponse.getHeaders());
 ```
 
-#### Features
+#### Example: Calling a new "Custom Endpoint" endpoint and decoding response into a struct
 
-Requests automatically include:
-- Authentication credentials from configuration
-- Retry logic for 5xx errors with exponential backoff
-- Error handling and exception mapping
-- Configured timeouts and headers
+```java
+// Define a class to hold the response
+class CustomEndpointResponse {
+    private boolean allowed;
+    private String reason;
+    
+    public boolean isAllowed() { return allowed; }
+    public void setAllowed(boolean allowed) { this.allowed = allowed; }
+    public String getReason() { return reason; }
+    public void setReason(String reason) { this.reason = reason; }
+}
+
+// Get raw response decoded into CustomEndpointResponse class
+APIExecutorResponse rawResponse = executor.executeWithDecode(request, CustomEndpointResponse.class).get();
+
+CustomEndpointResponse customEndpointResponse = rawResponse.getData();
+System.out.println("Response: " + customEndpointResponse);
+
+// You can access fields like headers, status code, etc. from rawResponse:
+System.out.println("Status Code: " + rawResponse.getStatusCode());
+System.out.println("Headers: " + rawResponse.getHeaders());
+```
 
 #### Documentation