feat: use build buulder chain for consistency

Author: SoulPancake

README.md

@@ -1199,7 +1199,8 @@ RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id
     .queryParam("page_size", "20")
     .queryParam("continuation_token", "eyJwayI6...")
     .body(requestBody)
-    .header("X-Experimental-Feature", "enabled");
+    .header("X-Experimental-Feature", "enabled")
+    .build();
 ```
 
 #### Example: Calling a new "Custom Endpoint" endpoint and handling raw response

docs/RawApi.md

@@ -10,7 +10,8 @@ OpenFgaClient client = new OpenFgaClient(config);
 // Build request
 RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/check")
     .pathParam("store_id", storeId)
-    .body(Map.of("tuple_key", Map.of("user", "user:jon", "relation", "reader", "object", "doc:1")));
+    .body(Map.of("tuple_key", Map.of("user", "user:jon", "relation", "reader", "object", "doc:1")))
+    .build();
 
 // Execute - typed response
 ApiResponse<CheckResponse> response = client.raw().send(request, CheckResponse.class).get();
@@ -34,15 +35,17 @@ RawRequestBuilder.builder(String method, String path)
 .queryParam(String key, String value)     // Add query parameter, URL-encoded
 .header(String key, String value)         // Add HTTP header
 .body(Object body)                        // Set request body (auto-serialized to JSON)
+.build()                                  // Complete the builder (required)
 ```
 
 **Example:**
 ```java
-RawRequestBuilder.builder("POST", "/stores/{store_id}/write")
+RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/write")
     .pathParam("store_id", "01ABC")
     .queryParam("dry_run", "true")
     .header("X-Request-ID", "uuid")
-    .body(requestObject);
+    .body(requestObject)
+    .build();
 ```
 
 ### RawApi
@@ -69,10 +72,11 @@ T getData()                            // Deserialized data
 
 ## Examples
 
-### Typed Response
+### GET Request
 ```java
 RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/feature")
-    .pathParam("store_id", storeId);
+    .pathParam("store_id", storeId)
+    .build();
 
 client.raw().send(request, FeatureResponse.class)
     .thenAccept(r -> System.out.println("Status: " + r.getStatusCode()));
@@ -83,7 +87,8 @@ client.raw().send(request, FeatureResponse.class)
 RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/bulk-delete")
     .pathParam("store_id", storeId)
     .queryParam("force", "true")
-    .body(new BulkDeleteRequest("2023-01-01", "user", 1000));
+    .body(new BulkDeleteRequest("2023-01-01", "user", 1000))
+    .build();
 
 client.raw().send(request, BulkDeleteResponse.class).get();
 ```
@@ -100,15 +105,17 @@ RawRequestBuilder.builder("GET", "/stores/{store_id}/items")
     .pathParam("store_id", storeId)
     .queryParam("page", "1")
     .queryParam("limit", "50")
-    .queryParam("sort", "created_at");
+    .queryParam("sort", "created_at")
+    .build();
 ```
 
 ### Custom Headers
 ```java
 RawRequestBuilder.builder("POST", "/stores/{store_id}/action")
     .header("X-Request-ID", UUID.randomUUID().toString())
     .header("X-Idempotency-Key", "key-123")
-    .body(data);
+    .body(data)
+    .build();
 ```
 
 ### Error Handling
@@ -125,29 +132,34 @@ client.raw().send(request, ResponseType.class)
 
 ### Map as Request Body
 ```java
-.body(Map.of(
-    "setting", "value",
-    "enabled", true,
-    "threshold", 100,
-    "options", List.of("opt1", "opt2")
-))
+RawRequestBuilder.builder("POST", "/stores/{store_id}/settings")
+    .pathParam("store_id", storeId)
+    .body(Map.of(
+        "setting", "value",
+        "enabled", true,
+        "threshold", 100,
+        "options", List.of("opt1", "opt2")
+    ))
+    .build();
 ```
 
 ## Notes
 
 - Path/query parameters are URL-encoded automatically
 - Authentication tokens injected from client config
-- Retries on 429, 5xx errors
 - `{store_id}` auto-replaced if not provided via `.pathParam()`
 
 ## Migration to Typed Methods
 
+When SDK adds typed methods for an endpoint, you can migrate from Raw API:
+
 ```java
 // Raw API
-client.raw().send(
-    RawRequestBuilder.builder("POST", "/stores/{store_id}/check").body(req),
-    CheckResponse.class
-).get();
+RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/check")
+    .body(req)
+    .build();
+    
+client.raw().send(request, CheckResponse.class).get();
 
 // Typed SDK (when available)
 client.check(req).get();

examples/raw-api/README.md

@@ -61,7 +61,8 @@ RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id
     .queryParam("page_size", "20")
     .queryParam("continuation_token", "eyJwayI6...")
     .body(requestBody)
-    .header("X-Custom-Header", "value");
+    .header("X-Custom-Header", "value")
+    .build();
 ```
 
 ### Response Handling

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

@@ -63,7 +63,7 @@ public static void main(String[] args) throws Exception {
     private static String listStoresExample(OpenFgaClient fgaClient) {
         try {
             // Build the raw request for GET /stores
-            RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores");
+            RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores").build();
 
             // Execute with typed response
             var response = fgaClient
@@ -102,7 +102,8 @@ private static String listStoresExample(OpenFgaClient fgaClient) {
     private static String createStoreForExamples(OpenFgaClient fgaClient) throws Exception {
         String storeName = "raw-api-example-" + UUID.randomUUID().toString().substring(0, 8);
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
-                .body(Map.of("name", storeName));
+                .body(Map.of("name", storeName))
+                .build();
 
         // Use typed response instead of manual JSON parsing
         var response = fgaClient.raw().send(request, CreateStoreResponse.class).get();
@@ -116,7 +117,8 @@ private static String createStoreForExamples(OpenFgaClient fgaClient) throws Exc
     private static void getStoreRawJsonExample(OpenFgaClient fgaClient, String storeId) {
         try {
             RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}")
-                    .pathParam("store_id", storeId);
+                    .pathParam("store_id", storeId)
+                    .build();
 
             // Execute and get raw JSON string
             var response = fgaClient.raw().send(request).get();
@@ -136,7 +138,8 @@ private static void getStoreRawJsonExample(OpenFgaClient fgaClient, String store
     private static void listStoresWithPaginationExample(OpenFgaClient fgaClient) {
         try {
             RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores")
-                    .queryParam("page_size", "2");
+                    .queryParam("page_size", "2")
+                    .build();
 
             var response = fgaClient
                     .raw()
@@ -167,7 +170,8 @@ private static void createStoreWithHeadersExample(OpenFgaClient fgaClient) {
             RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
                     .header("X-Example-Header", "custom-value")
                     .header("X-Request-ID", "req-" + UUID.randomUUID())
-                    .body(Map.of("name", storeName));
+                    .body(Map.of("name", storeName))
+                    .build();
 
             var response = fgaClient.raw().send(request).get();
 
@@ -190,7 +194,8 @@ private static void errorHandlingExample(OpenFgaClient fgaClient) {
         try {
             // Try to get a non-existent store
             RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}")
-                    .pathParam("store_id", "01ZZZZZZZZZZZZZZZZZZZZZZZ9");
+                    .pathParam("store_id", "01ZZZZZZZZZZZZZZZZZZZZZZZ9")
+                    .build();
 
             var response = fgaClient.raw().send(request).get();
 

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

@@ -16,7 +16,8 @@
  * <pre>{@code
  * RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/endpoint")
  *     .pathParam("store_id", storeId)
- *     .body(requestData);
+ *     .body(requestData)
+ *     .build();
  *
  * // Typed response
  * ApiResponse<ResponseType> response = client.raw().send(request, ResponseType.class).get();

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

@@ -14,7 +14,8 @@
  * RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/endpoint")
  *     .pathParam("store_id", storeId)
  *     .queryParam("limit", "50")
- *     .body(requestObject);
+ *     .body(requestObject)
+ *     .build();
  * }</pre>
  */
 public class RawRequestBuilder {
@@ -114,6 +115,18 @@ public RawRequestBuilder body(Object body) {
         this.body = body;
         return this;
     }
+    /**
+     * Builds and returns the request for use with the Raw API.
+     * This method must be called to complete request construction.
+     *
+     * <p>This is required for consistency with other OpenFGA SDKs (e.g., Go SDK)
+     * and follows the standard builder pattern.</p>
+     *
+     * @return This builder instance (ready to be passed to {@link RawApi#send})
+     */
+    public RawRequestBuilder build() {
+        return this;
+    }
 
     String getMethod() {
         return method;

src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java

@@ -50,7 +50,7 @@ public void rawRequest_listStores() throws Exception {
         createStoreUsingRawRequest(storeName);
 
         // Use raw API to list stores (equivalent to GET /stores)
-        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores");
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores").build();
 
         ApiResponse<ListStoresResponse> response =
                 fga.raw().send(request, ListStoresResponse.class).get();
@@ -83,7 +83,8 @@ public void rawRequest_createStore_typedResponse() throws Exception {
         requestBody.put("name", storeName);
 
         // Use raw API to create store (equivalent to POST /stores)
-        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores").body(requestBody);
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("POST", "/stores").body(requestBody).build();
 
         ApiResponse<CreateStoreResponse> response =
                 fga.raw().send(request, CreateStoreResponse.class).get();
@@ -112,7 +113,8 @@ public void rawRequest_createStore_rawJsonResponse() throws Exception {
         requestBody.put("name", storeName);
 
         // Use raw API to create store and get raw JSON response
-        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores").body(requestBody);
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("POST", "/stores").body(requestBody).build();
 
         ApiResponse<String> response = fga.raw().send(request).get();
 
@@ -142,8 +144,9 @@ public void rawRequest_getStore_withPathParams() throws Exception {
         String storeId = createStoreUsingRawRequest(storeName);
 
         // Use raw API to get store details (equivalent to GET /stores/{store_id})
-        RawRequestBuilder request =
-                RawRequestBuilder.builder("GET", "/stores/{store_id}").pathParam("store_id", storeId);
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}")
+                .pathParam("store_id", storeId)
+                .build();
 
         ApiResponse<GetStoreResponse> response =
                 fga.raw().send(request, GetStoreResponse.class).get();
@@ -170,7 +173,8 @@ public void rawRequest_automaticStoreIdReplacement() throws Exception {
         fga.setStoreId(storeId);
 
         // Use raw API WITHOUT providing store_id path param - it should be auto-replaced
-        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}");
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("GET", "/stores/{store_id}").build();
 
         ApiResponse<GetStoreResponse> response =
                 fga.raw().send(request, GetStoreResponse.class).get();
@@ -221,7 +225,8 @@ public void rawRequest_writeAuthorizationModel() throws Exception {
 
         // Use raw API to write authorization model
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/authorization-models")
-                .body(requestBody);
+                .body(requestBody)
+                .build();
 
         ApiResponse<WriteAuthorizationModelResponse> response =
                 fga.raw().send(request, WriteAuthorizationModelResponse.class).get();
@@ -252,7 +257,8 @@ public void rawRequest_readAuthorizationModels_withQueryParams() throws Exceptio
         // Use raw API to read authorization models with query parameters
         RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/authorization-models")
                 .queryParam("page_size", "10")
-                .queryParam("continuation_token", "");
+                .queryParam("continuation_token", "")
+                .build();
 
         ApiResponse<ReadAuthorizationModelsResponse> response =
                 fga.raw().send(request, ReadAuthorizationModelsResponse.class).get();
@@ -295,16 +301,12 @@ public void rawRequest_check() throws Exception {
         tupleKey.put("object", "document:budget");
         checkBody.put("tuple_key", tupleKey);
 
-        RawRequestBuilder request =
-                RawRequestBuilder.builder("POST", "/stores/{store_id}/check").body(checkBody);
+        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/check")
+                .body(checkBody)
+                .build();
 
         ApiResponse<CheckResponse> response =
                 fga.raw().send(request, CheckResponse.class).get();
-
-        // Verify response
-        assertNotNull(response);
-        assertEquals(200, response.getStatusCode());
-        assertNotNull(response.getData());
         assertTrue(response.getData().getAllowed(), "Alice should be allowed to read the document");
 
         System.out.println("✓ Successfully performed check using raw request");
@@ -325,7 +327,8 @@ public void rawRequest_withCustomHeaders() throws Exception {
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
                 .body(requestBody)
                 .header("X-Custom-Header", "custom-value")
-                .header("X-Request-ID", "test-123");
+                .header("X-Request-ID", "test-123")
+                .build();
 
         ApiResponse<CreateStoreResponse> response =
                 fga.raw().send(request, CreateStoreResponse.class).get();
@@ -343,8 +346,9 @@ public void rawRequest_withCustomHeaders() throws Exception {
     @Test
     public void rawRequest_errorHandling_notFound() throws Exception {
         // Try to get a non-existent store
-        RawRequestBuilder request =
-                RawRequestBuilder.builder("GET", "/stores/{store_id}").pathParam("store_id", "non-existent-store-id");
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}")
+                .pathParam("store_id", "non-existent-store-id")
+                .build();
 
         // Should throw an exception
         try {
@@ -372,7 +376,9 @@ public void rawRequest_listStores_withPagination() throws Exception {
         }
 
         // Use raw API to list stores with pagination
-        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores").queryParam("page_size", "2");
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores")
+                .queryParam("page_size", "2")
+                .build();
 
         ApiResponse<ListStoresResponse> response =
                 fga.raw().send(request, ListStoresResponse.class).get();
@@ -396,7 +402,8 @@ private String createStoreUsingRawRequest(String storeName) throws Exception {
         Map<String, Object> requestBody = new HashMap<>();
         requestBody.put("name", storeName);
 
-        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores").body(requestBody);
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("POST", "/stores").body(requestBody).build();
 
         ApiResponse<CreateStoreResponse> response =
                 fga.raw().send(request, CreateStoreResponse.class).get();
@@ -431,7 +438,8 @@ private String writeSimpleAuthorizationModel(String storeId) throws Exception {
 
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/authorization-models")
                 .pathParam("store_id", storeId)
-                .body(requestBody);
+                .body(requestBody)
+                .build();
 
         ApiResponse<WriteAuthorizationModelResponse> response =
                 fga.raw().send(request, WriteAuthorizationModelResponse.class).get();
@@ -451,7 +459,8 @@ private void writeTupleUsingRawRequest(String storeId, String user, String relat
 
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/write")
                 .pathParam("store_id", storeId)
-                .body(requestBody);
+                .body(requestBody)
+                .build();
 
         fga.raw().send(request, Object.class).get();
     }