feat: refactor add typed resp in example

Author: SoulPancake

examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java

@@ -3,11 +3,12 @@
 import dev.openfga.sdk.api.client.OpenFgaClient;
 import dev.openfga.sdk.api.client.RawRequestBuilder;
 import dev.openfga.sdk.api.configuration.ClientConfiguration;
-import dev.openfga.sdk.api.model.CreateStoreRequest;
+import dev.openfga.sdk.api.model.CreateStoreResponse;
 import dev.openfga.sdk.api.model.ListStoresResponse;
 import dev.openfga.sdk.api.model.Store;
 import java.util.List;
 import java.util.Map;
+import java.util.UUID;
 
 /**
  * Example demonstrating Raw API usage.
@@ -16,6 +17,11 @@
  * that are not yet wrapped by the SDK's typed methods.
  *
  * The example uses real OpenFGA endpoints to demonstrate actual functionality.
+ *
+ * Note: Examples use .get() to block for simplicity. In production, use async patterns:
+ * - thenApply/thenAccept for chaining
+ * - thenCompose for sequential async operations
+ * - CompletableFuture.allOf for parallel operations
  */
 public class RawApiExample {
 
@@ -94,26 +100,14 @@ private static String listStoresExample(OpenFgaClient fgaClient) {
      * Helper method to create a store for examples.
      */
     private static String createStoreForExamples(OpenFgaClient fgaClient) throws Exception {
-        String storeName = "raw-api-example-" + System.currentTimeMillis();
+        String storeName = "raw-api-example-" + UUID.randomUUID().toString().substring(0, 8);
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
                 .body(Map.of("name", storeName));
 
-        var response = fgaClient.raw().send(request).get();
-        String rawJson = response.getData();
+        // Use typed response instead of manual JSON parsing
+        var response = fgaClient.raw().send(request, CreateStoreResponse.class).get();
         System.out.println("  Created store: " + storeName);
-
-        // Extract store ID from JSON (simple parsing)
-        String idPrefix = "\"id\":\"";
-        int idStart = rawJson.indexOf(idPrefix);
-        if (idStart == -1) {
-            throw new RuntimeException("Could not find store ID in response: " + rawJson);
-        }
-        idStart += idPrefix.length();
-        int idEnd = rawJson.indexOf("\"", idStart);
-        if (idEnd == -1) {
-            throw new RuntimeException("Could not parse store ID from response: " + rawJson);
-        }
-        return rawJson.substring(idStart, idEnd);
+        return response.getData().getId();
     }
 
     /**
@@ -169,10 +163,10 @@ private static void listStoresWithPaginationExample(OpenFgaClient fgaClient) {
      */
     private static void createStoreWithHeadersExample(OpenFgaClient fgaClient) {
         try {
-            String storeName = "raw-api-custom-headers-" + System.currentTimeMillis();
+            String storeName = "raw-api-custom-headers-" + UUID.randomUUID().toString().substring(0, 8);
             RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
                     .header("X-Example-Header", "custom-value")
-                    .header("X-Request-ID", "req-" + System.currentTimeMillis())
+                    .header("X-Request-ID", "req-" + UUID.randomUUID())
                     .body(Map.of("name", storeName));
 
             var response = fgaClient.raw().send(request).get();

src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java

@@ -2,6 +2,7 @@
 
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Set;
 
 /**
  * Fluent builder for constructing HTTP requests to OpenFGA API endpoints.
@@ -17,6 +18,9 @@
  * }</pre>
  */
 public class RawRequestBuilder {
+    private static final Set<String> VALID_HTTP_METHODS =
+            Set.of("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS");
+
     private final String method;
     private final String path;
     private final Map<String, String> pathParams;
@@ -36,9 +40,10 @@ private RawRequestBuilder(String method, String path) {
     /**
      * Creates a new RawRequestBuilder instance.
      *
-     * @param method HTTP method (GET, POST, PUT, DELETE, etc.)
+     * @param method HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
      * @param path API path with optional placeholders like {store_id}
      * @return New RawRequestBuilder instance
+     * @throws IllegalArgumentException if method or path is invalid
      */
     public static RawRequestBuilder builder(String method, String path) {
         if (method == null || method.trim().isEmpty()) {
@@ -47,7 +52,14 @@ public static RawRequestBuilder builder(String method, String path) {
         if (path == null || path.trim().isEmpty()) {
             throw new IllegalArgumentException("Path cannot be null or empty");
         }
-        return new RawRequestBuilder(method.toUpperCase(), path);
+
+        String upperMethod = method.toUpperCase();
+        if (!VALID_HTTP_METHODS.contains(upperMethod)) {
+            throw new IllegalArgumentException(
+                    "Invalid HTTP method: " + method + ". Valid methods: " + VALID_HTTP_METHODS);
+        }
+
+        return new RawRequestBuilder(upperMethod, path);
     }
 
     /**

src/test/java/dev/openfga/sdk/api/client/RawApiTest.java

@@ -134,6 +134,25 @@ public void rawRequestBuilder_throwsExceptionForEmptyPath() {
         assertThrows(IllegalArgumentException.class, () -> RawRequestBuilder.builder("GET", ""));
     }
 
+    @Test
+    public void rawRequestBuilder_throwsExceptionForInvalidHttpMethod() {
+        IllegalArgumentException exception = assertThrows(
+                IllegalArgumentException.class, () -> RawRequestBuilder.builder("INVALID", "/test"));
+        assertTrue(exception.getMessage().contains("Invalid HTTP method"));
+    }
+
+    @Test
+    public void rawRequestBuilder_acceptsValidHttpMethods() {
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("GET", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("POST", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("PUT", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("PATCH", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("DELETE", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("HEAD", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("OPTIONS", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("get", "/test"));
+    }
+
     @Test
     public void rawApi_canSendGetRequestWithTypedResponse() throws Exception {
         // Setup mock server