feat: rename and refactor to APIExecutor for consistency

Author: SoulPancake

CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## [Unreleased](https://github.com/openfga/java-sdk/compare/v0.9.4...HEAD)
 
+### Changed
+- **BREAKING**: Renamed "Raw API" to "API Executor" throughout the SDK for consistency with Go SDK naming conventions
+  - `RawApi` class renamed to `ApiExecutor`
+  - `RawRequestBuilder` class renamed to `ApiExecutorRequestBuilder`
+  - `OpenFgaClient.raw()` method renamed to `OpenFgaClient.apiExecutor()`
+  - All documentation updated to refer to "API Executor" instead of "Raw API"
+  - Example directory `examples/raw-api` renamed to `examples/api-executor`
+  - Documentation file `docs/RawApi.md` renamed to `docs/ApiExecutor.md`
+  
+  **Migration Guide**: Update your code as follows:
+  ```java
+  // Before
+  RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/endpoint")
+      .pathParam("store_id", storeId)
+      .body(requestData)
+      .build();
+  ApiResponse<ResponseType> response = client.raw().send(request, ResponseType.class).get();
+  
+  // After
+  ApiExecutorRequestBuilder request = ApiExecutorRequestBuilder.builder("POST", "/stores/{store_id}/endpoint")
+      .pathParam("store_id", storeId)
+      .body(requestData)
+      .build();
+  ApiResponse<ResponseType> response = client.apiExecutor().send(request, ResponseType.class).get();
+  ```
+
 ## v0.9.4
 
 ### [0.9.4](https://github.com/openfga/java-sdk/compare/v0.9.3...v0.9.4) (2025-12-05)

README.md

@@ -1170,14 +1170,14 @@ try {
 
 ### Calling Other Endpoints
 
-The Raw API provides direct HTTP access to OpenFGA endpoints not yet wrapped by the SDK. It maintains the SDK's client configuration including authentication, telemetry, retries, and error handling.
+The API Executor provides direct HTTP access to OpenFGA endpoints not yet wrapped by the SDK. It maintains the SDK's client configuration including authentication, telemetry, retries, and error handling.
 
 Use cases:
 - Calling endpoints not yet supported by the SDK
 - Using an SDK version that lacks support for a particular endpoint
 - Accessing custom endpoints that extend the OpenFGA API
 
-Initialize the SDK normally and access the Raw API via the `fgaClient` instance:
+Initialize the SDK normally and access the API Executor via the `fgaClient` instance:
 
 ```java
 // Initialize the client, same as above
@@ -1194,7 +1194,7 @@ Map<String, Object> requestBody = Map.of(
 );
 
 // Build the request
-RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/custom-endpoint")
+ApiExecutorRequestBuilder request = ApiExecutorRequestBuilder.builder("POST", "/stores/{store_id}/custom-endpoint")
     .pathParam("store_id", storeId)
     .queryParam("page_size", "20")
     .queryParam("continuation_token", "eyJwayI6...")
@@ -1207,7 +1207,7 @@ RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id
 
 ```java
 // Get raw response without automatic decoding
-ApiResponse<String> rawResponse = fgaClient.raw().send(request).get();
+ApiResponse<String> rawResponse = fgaClient.apiExecutor().send(request).get();
 
 String rawJson = rawResponse.getData();
 System.out.println("Response: " + rawJson);
@@ -1232,7 +1232,7 @@ class CustomEndpointResponse {
 }
 
 // Get response decoded into CustomEndpointResponse class
-ApiResponse<CustomEndpointResponse> response = fgaClient.raw()
+ApiResponse<CustomEndpointResponse> response = fgaClient.apiExecutor()
     .send(request, CustomEndpointResponse.class)
     .get();
 
@@ -1245,11 +1245,11 @@ System.out.println("Status Code: " + response.getStatusCode());
 System.out.println("Headers: " + response.getHeaders());
 ```
 
-For a complete working example, see [examples/raw-api](examples/raw-api).
+For a complete working example, see [examples/api-executor](examples/api-executor).
 
 #### Documentation
 
-See [docs/RawApi.md](docs/RawApi.md) for complete API reference and examples.
+See [docs/ApiExecutor.md](docs/ApiExecutor.md) for complete API reference and examples.
 
 ### API Endpoints
 

docs/RawApi.md docs/ApiExecutor.mddocs/RawApi.md renamed to docs/ApiExecutor.md

@@ -1,4 +1,4 @@
-# Raw API
+# API Executor
 
 Direct HTTP access to OpenFGA endpoints.
 
@@ -8,25 +8,25 @@ Direct HTTP access to OpenFGA endpoints.
 OpenFgaClient client = new OpenFgaClient(config);
 
 // Build request
-RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/check")
+ApiExecutorRequestBuilder request = ApiExecutorRequestBuilder.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")))
     .build();
 
 // Execute - typed response
-ApiResponse<CheckResponse> response = client.raw().send(request, CheckResponse.class).get();
+ApiResponse<CheckResponse> response = client.apiExecutor().send(request, CheckResponse.class).get();
 
 // Execute - raw JSON
-ApiResponse<String> rawResponse = client.raw().send(request).get();
+ApiResponse<String> rawResponse = client.apiExecutor().send(request).get();
 ```
 
 ## API Reference
 
-### RawRequestBuilder
+### ApiExecutorRequestBuilder
 
 **Factory:**
 ```java
-RawRequestBuilder.builder(String method, String path)
+ApiExecutorRequestBuilder.builder(String method, String path)
 ```
 
 **Methods:**
@@ -40,25 +40,25 @@ RawRequestBuilder.builder(String method, String path)
 
 **Example:**
 ```java
-RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/write")
+ApiExecutorRequestBuilder request = ApiExecutorRequestBuilder.builder("POST", "/stores/{store_id}/write")
     .pathParam("store_id", "01ABC")
     .queryParam("dry_run", "true")
     .header("X-Request-ID", "uuid")
     .body(requestObject)
     .build();
 ```
 
-### RawApi
+### ApiExecutor
 
 **Access:**
 ```java
-RawApi rawApi = client.raw();
+RawApi rawApi = client.apiExecutor();
 ```
 
 **Methods:**
 ```java
-CompletableFuture<ApiResponse<String>> send(RawRequestBuilder request)
-CompletableFuture<ApiResponse<T>> send(RawRequestBuilder request, Class<T> responseType)
+CompletableFuture<ApiResponse<String>> send(ApiExecutorRequestBuilder request)
+CompletableFuture<ApiResponse<T>> send(ApiExecutorRequestBuilder request, Class<T> responseType)
 ```
 
 ### ApiResponse<T>
@@ -74,34 +74,34 @@ T getData()                            // Deserialized data
 
 ### GET Request
 ```java
-RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/feature")
+ApiExecutorRequestBuilder request = ApiExecutorRequestBuilder.builder("GET", "/stores/{store_id}/feature")
     .pathParam("store_id", storeId)
     .build();
 
-client.raw().send(request, FeatureResponse.class)
+client.apiExecutor().send(request, FeatureResponse.class)
     .thenAccept(r -> System.out.println("Status: " + r.getStatusCode()));
 ```
 
 ### POST with Body
 ```java
-RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/bulk-delete")
+ApiExecutorRequestBuilder request = ApiExecutorRequestBuilder.builder("POST", "/stores/{store_id}/bulk-delete")
     .pathParam("store_id", storeId)
     .queryParam("force", "true")
     .body(new BulkDeleteRequest("2023-01-01", "user", 1000))
     .build();
 
-client.raw().send(request, BulkDeleteResponse.class).get();
+client.apiExecutor().send(request, BulkDeleteResponse.class).get();
 ```
 
 ### Raw JSON Response
 ```java
-ApiResponse<String> response = client.raw().send(request).get();
+ApiResponse<String> response = client.apiExecutor().send(request).get();
 String json = response.getRawResponse(); // Raw JSON
 ```
 
 ### Query Parameters
 ```java
-RawRequestBuilder.builder("GET", "/stores/{store_id}/items")
+ApiExecutorRequestBuilder.builder("GET", "/stores/{store_id}/items")
     .pathParam("store_id", storeId)
     .queryParam("page", "1")
     .queryParam("limit", "50")
@@ -111,7 +111,7 @@ RawRequestBuilder.builder("GET", "/stores/{store_id}/items")
 
 ### Custom Headers
 ```java
-RawRequestBuilder.builder("POST", "/stores/{store_id}/action")
+ApiExecutorRequestBuilder.builder("POST", "/stores/{store_id}/action")
     .header("X-Request-ID", UUID.randomUUID().toString())
     .header("X-Idempotency-Key", "key-123")
     .body(data)
@@ -120,7 +120,7 @@ RawRequestBuilder.builder("POST", "/stores/{store_id}/action")
 
 ### Error Handling
 ```java
-client.raw().send(request, ResponseType.class)
+client.apiExecutor().send(request, ResponseType.class)
     .exceptionally(e -> {
         if (e.getCause() instanceof FgaError) {
             FgaError error = (FgaError) e.getCause();
@@ -132,7 +132,7 @@ client.raw().send(request, ResponseType.class)
 
 ### Map as Request Body
 ```java
-RawRequestBuilder.builder("POST", "/stores/{store_id}/settings")
+ApiExecutorRequestBuilder.builder("POST", "/stores/{store_id}/settings")
     .pathParam("store_id", storeId)
     .body(Map.of(
         "setting", "value",
@@ -151,15 +151,15 @@ RawRequestBuilder.builder("POST", "/stores/{store_id}/settings")
 
 ## Migration to Typed Methods
 
-When SDK adds typed methods for an endpoint, you can migrate from Raw API:
+When SDK adds typed methods for an endpoint, you can migrate from API Executor:
 
 ```java
-// Raw API
-RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/check")
+// API Executor
+ApiExecutorRequestBuilder request = ApiExecutorRequestBuilder.builder("POST", "/stores/{store_id}/check")
     .body(req)
     .build();
 
-client.raw().send(request, CheckResponse.class).get();
+client.apiExecutor().send(request, CheckResponse.class).get();
 
 // Typed SDK (when available)
 client.check(req).get();

examples/README.md

@@ -13,6 +13,6 @@ A simple example that creates a store, runs a set of calls against it including
 #### Streaming Examples
 - `streamed-list-objects/` - Demonstrates using the StreamedListObjects API to retrieve large result sets without pagination limits
 
-#### Raw API Examples
-- `raw-api/` - Demonstrates direct HTTP access to OpenFGA endpoints not yet wrapped by the SDK, maintaining SDK configuration (authentication, retries, error handling)
+#### API Executor Examples
+- `api-executor/` - Demonstrates direct HTTP access to OpenFGA endpoints not yet wrapped by the SDK, maintaining SDK configuration (authentication, retries, error handling)
 

examples/raw-api/Makefile examples/api-executor/Makefileexamples/raw-api/Makefile renamed to examples/api-executor/Makefile

@@ -1,10 +1,10 @@
-# Raw API Example
+# API Executor Example
 
-Demonstrates using the Raw API to call OpenFGA endpoints that are not yet wrapped by the SDK.
+Demonstrates using the API Executor to call OpenFGA endpoints that are not yet wrapped by the SDK.
 
-## What is the Raw API?
+## What is the API Executor?
 
-The Raw API provides direct HTTP access to OpenFGA endpoints while maintaining the SDK's configuration (authentication, telemetry, retries, and error handling).
+The API Executor provides direct HTTP access to OpenFGA endpoints while maintaining the SDK's configuration (authentication, telemetry, retries, and error handling).
 
 Use cases:
 - Calling endpoints not yet wrapped by the SDK
@@ -26,7 +26,7 @@ docker run -p 8080:8080 openfga/openfga run
 ./gradlew build
 
 # Then run the example
-cd examples/raw-api
+cd examples/api-executor
 ./gradlew run
 ```
 
@@ -39,7 +39,7 @@ make run
 
 ## What it does
 
-The example demonstrates Raw API capabilities using real OpenFGA endpoints:
+The example demonstrates API Executor capabilities using real OpenFGA endpoints:
 
 1. **List Stores (GET with typed response)**: Lists all stores and deserializes into `ListStoresResponse`
 2. **Get Store (GET with raw JSON)**: Retrieves a single store and returns the raw JSON string
@@ -56,7 +56,7 @@ All requests will succeed (except #5 which intentionally triggers an error for d
 Build requests using the builder pattern:
 
 ```java
-RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/custom-endpoint")
+ApiExecutorRequestBuilder request = ApiExecutorRequestBuilder.builder("POST", "/stores/{store_id}/custom-endpoint")
     .pathParam("store_id", storeId)
     .queryParam("page_size", "20")
     .queryParam("continuation_token", "eyJwayI6...")
@@ -70,7 +70,7 @@ RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id
 
 **Typed Response (automatic deserialization):**
 ```java
-client.raw().send(request, CustomResponse.class)
+client.apiExecutor().send(request, CustomResponse.class)
     .thenAccept(response -> {
         System.out.println("Data: " + response.getData());
         System.out.println("Status: " + response.getStatusCode());
@@ -79,7 +79,7 @@ client.raw().send(request, CustomResponse.class)
 
 **Raw JSON Response:**
 ```java
-client.raw().send(request)
+client.apiExecutor().send(request)
     .thenAccept(response -> {
         System.out.println("Raw JSON: " + response.getRawResponse());
     });
@@ -96,14 +96,14 @@ Requests automatically include:
 
 ## Code Structure
 
-- `RawApiExample.java`: Example demonstrating Raw API usage with real OpenFGA endpoints
+- `ApiExecutorExample.java`: Example demonstrating API Executor usage with real OpenFGA endpoints
 
 ## Notes
 
-This example uses real OpenFGA endpoints (`/stores`, `/stores/{store_id}`) to demonstrate actual functionality. The Raw API can be used with any OpenFGA endpoint, including custom endpoints if you have extended the API.
+This example uses real OpenFGA endpoints (`/stores`, `/stores/{store_id}`) to demonstrate actual functionality. The API Executor can be used with any OpenFGA endpoint, including custom endpoints if you have extended the API.
 
 ## See Also
 
-- [Raw API Documentation](../../docs/RawApi.md)
+- [API Executor Documentation](../../docs/RawApi.md)
 - [OpenFGA API Reference](https://openfga.dev/api)
 

examples/raw-api/README.md examples/api-executor/README.mdexamples/raw-api/README.md renamed to examples/api-executor/README.md

@@ -4,7 +4,7 @@ plugins {
 }
 
 application {
-    mainClass = 'dev.openfga.sdk.example.RawApiExample'
+    mainClass = 'dev.openfga.sdk.example.ApiExecutorExample'
 }
 
 repositories {