feat: Add APIExecutor for calling arbitrary API endpoints#298
Conversation
|
Important Review skippedAuto incremental reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the Use the checkbox below for a quick retry:
WalkthroughThe pull request adds a raw HTTP request capability across the OpenFGA TypeScript SDK, enabling developers to make arbitrary HTTP calls to OpenFGA endpoints. A new Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related issues
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Documentation Updates 2 document(s) were updated by changes in this PR: Custom HTTP Headers SupportView Changes@@ -1,5 +1,5 @@
## Configuring HTTP Headers in OpenFGA SDKs
-OpenFGA SDKs (.NET, Python, Go) support configuring default HTTP headers globally for all requests and overriding them on a per-request basis. This document explains how to set headers, describes validation and reserved header rules, and provides examples for each SDK. It also details how headers are merged and the interface changes introduced to support this functionality.
+OpenFGA SDKs (.NET, Python, Go, JavaScript/TypeScript) support configuring default HTTP headers globally for all requests and overriding them on a per-request basis. This document explains how to set headers, describes validation and reserved header rules, and provides examples for each SDK. It also details how headers are merged and the interface changes introduced to support this functionality.
### .NET SDK
@@ -162,7 +162,58 @@
#### Validation Rules and Reserved Headers
The Go SDK does not explicitly document a reserved header list or detailed validation rules for headers. However, authentication headers such as `Authorization` are always set internally by the SDK, regardless of whether a custom HTTPClient is provided. If you provide both a custom HTTPClient and use ClientCredentials authentication, the SDK will override your HTTPClient with an OAuth2-enabled client to ensure proper authentication. Attempts to set reserved headers like `Authorization` in your custom headers will be ignored in favor of the SDK-managed value. There are no explicit header injection prevention mechanisms documented, so avoid including newline characters in header values.
-## Go SDK
+---
+
+### JavaScript/TypeScript SDK
+
+#### Calling Other Endpoints with apiExecutor
+The JavaScript SDK provides an `apiExecutor` method for making raw HTTP calls to any OpenFGA endpoint, including endpoints not yet wrapped by the SDK. This is useful if you need to:
+
+- Call a new or experimental endpoint not yet supported by the SDK
+- Use a custom or extended OpenFGA API
+- Set custom headers or parameters for advanced use cases
+
+The `apiExecutor` method is available on the `OpenFgaClient` instance:
+
+```javascript
+const response = await fgaClient.apiExecutor({
+ operationName: 'CustomEndpoint', // For telemetry/logging
+ method: 'POST',
+ path: '/stores/{store_id}/custom-endpoint',
+ pathParams: { store_id: process.env.FGA_STORE_ID },
+ body: {
+ user: 'user:bob',
+ action: 'custom_action',
+ resource: 'resource:123',
+ },
+ queryParams: {
+ page_size: 20,
+ },
+});
+```
+
+You can pass custom headers in the `options` parameter. These headers are merged with global configuration headers, with per-request headers taking precedence:
+
+```javascript
+const response = await fgaClient.apiExecutor({
+ method: 'GET',
+ path: '/stores/{store_id}/authorization-models',
+ pathParams: { store_id: 'your-store-id' },
+}, {
+ headers: {
+ 'X-Request-ID': '123e4567-e89b-12d3-a456-426614174000',
+ 'X-Custom-Header': 'custom-value',
+ }
+});
+```
+
+The method automatically handles authentication, retries, telemetry, and error handling according to your client configuration.
+
+For more details and usage examples, see the [JavaScript SDK README](https://github.com/openfga/js-sdk#calling-other-endpoints).
+
+---
+
+### Go SDK
#### Calling Other Endpoints with APIExecutor
The Go SDK provides an `APIExecutor` interface for making raw HTTP calls to any OpenFGA endpoint, including endpoints not yet wrapped by the SDK. This is useful if you need to:
@@ -207,11 +258,12 @@
- Review SDK documentation and source for updates on reserved headers and validation rules, especially if you need to set headers that may conflict with protocol or SDK-managed headers.
### Comparison Table
-| SDK | Global Headers Config | Per-Request Headers | Header Merging | Reserved Headers | Injection Prevention |
-|---------|----------------------|---------------------|----------------|------------------|---------------------|
-| .NET | `DefaultHeaders` in `ClientConfiguration` | `Headers` in options parameter | Per-request > Auth > Default (case-insensitive) | Explicitly blocked, strict list | Yes (CR/LF check) |
-| Python | `headers` in `ClientConfiguration` | `headers` in `options` dict | Per-request > Default | Not documented, some set internally | Yes (sanitization) |
-| Go | `DefaultHeaders` in `ClientConfiguration` | `Headers` in `RequestOptions` | Per-request > Default | Not documented | Not documented |
+| SDK | Global Headers Config | Per-Request Headers | Header Merging | Reserved Headers | Injection Prevention |
+|--------------------|----------------------|---------------------|----------------|------------------|---------------------|
+| .NET | `DefaultHeaders` in `ClientConfiguration` | `Headers` in options parameter | Per-request > Auth > Default (case-insensitive) | Explicitly blocked, strict list | Yes (CR/LF check) |
+| Python | `headers` in `ClientConfiguration` | `headers` in `options` dict | Per-request > Default | Not documented, some set internally | Yes (sanitization) |
+| JavaScript/TypeScript | Configuration headers | `headers` in `options` | Per-request > Default | Not documented | Not documented |
+| Go | `DefaultHeaders` in `ClientConfiguration` | `Headers` in `RequestOptions` | Per-request > Default | Not documented | Not documented |
---
StreamedListObjects Feature OverviewView Changes@@ -81,9 +81,24 @@
For more details, see the [Go SDK StreamedListObjects Example](https://github.com/openfga/go-sdk/blob/main/example/streamed_list_objects/main.go).
-### JS and .NET SDKs
+### JS SDK
The JS SDK supports StreamedListObjects as of version v0.9.2-beta.1. The method streams results using async iterators, allowing you to process each object as it arrives. See the [documentation](#streamed-list-objects) for usage details.
+Additionally, the JS SDK provides an `apiExecutor` method on `OpenFgaClient` that can be used to call arbitrary API endpoints, including streaming endpoints like `/streamed-list-objects` or other endpoints that don't yet have dedicated SDK methods. The `apiExecutor` method acts as an escape hatch while still providing SDK benefits like authentication, configuration, retries, and error handling.
+
+**Example:**
+```javascript
+const response = await fgaClient.apiExecutor({
+ operationName: 'CustomEndpoint',
+ method: 'POST',
+ path: '/stores/{store_id}/custom-endpoint',
+ pathParams: { store_id: process.env.FGA_STORE_ID },
+ body: { /* request body */ },
+ queryParams: { page_size: 20 },
+});
+```
+
+### .NET SDK
The .NET SDK does not currently support StreamedListObjects. There is an open feature request and ongoing work to add support ([.NET issue](https://github.com/openfga/dotnet-sdk/issues/110)). The current workaround is to call the `/streamed-list-objects` API directly.
## Benefits Over ListObjectsHow did I do? Any feedback? |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
tests/rawRequest.test.ts (3)
100-119: Consider using a more meaningful assertion.The test relies on the implicit behavior that nock will fail if the header is not matched. While this works, the
expect(true).toBe(true)assertion on line 118 is a code smell. Consider adding an explicit assertion that provides more value.🔎 Suggested improvement
- // If we get here without error, the Content-Type header was correctly applied - expect(true).toBe(true); + // Nock would have thrown if the Content-Type header was missing + expect(nock.isDone()).toBe(true);
191-195: Same pattern of trivial assertion.This applies to the custom headers test as well. Consider using
expect(nock.isDone()).toBe(true)for a more meaningful assertion.
246-250: Same pattern of trivial assertion in authentication test.Consider using
expect(nock.isDone()).toBe(true)here as well for consistency.api.ts (1)
833-836: Consider also handling DELETE with body.While less common, HTTP DELETE requests can also have a body. The current implementation only sets
Content-Typefor POST/PUT/PATCH. If a user passes a body with DELETE, it will be serialized (line 841-843) but without theContent-Typeheader.🔎 Suggested fix to include DELETE with body support
// Set Content-Type for requests with body - if (body !== undefined && (method === "POST" || method === "PUT" || method === "PATCH")) { + if (body !== undefined) { localVarHeaderParameter["Content-Type"] = "application/json"; }Alternatively, if you want to keep the current behavior to avoid unexpected Content-Type headers on bodyless requests, the current implementation is acceptable since this is an escape hatch and users can manually set headers via
options.headers.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
api.tsclient.tstests/rawRequest.test.ts
🧰 Additional context used
🧬 Code graph analysis (2)
client.ts (2)
apiModel.ts (3)
CheckRequest(277-314)TupleKey(1432-1457)CheckRequestTupleKey(322-341)common.ts (1)
PromiseResult(116-116)
api.ts (2)
common.ts (8)
setSearchParams(51-66)DUMMY_BASE_URL(23-23)serializeDataIfNeeded(88-96)toPathString(102-104)RequestArgs(30-33)PromiseResult(116-116)createRequestFunction(280-347)CallResult(112-114)base.ts (1)
RequestArgs(15-18)
🔇 Additional comments (12)
tests/rawRequest.test.ts (4)
1-30: Test setup and imports look correct.The test file follows the existing test patterns in the codebase, properly setting up nock mocking and disabling network connections.
32-80: GET request tests are comprehensive and well-structured.The tests cover successful GET requests, query parameters, and $response access pattern. Good coverage.
140-153: Good test coverage for DELETE with 204 No Content response.The test correctly handles the 204 status code scenario and validates via
$response.status.
198-231: Error handling tests properly validate SDK error mapping.Tests correctly verify that 404 responses map to
FgaApiNotFoundErrorand 400 responses map toFgaApiValidationError, ensuring the rawRequest inherits SDK error handling.client.ts (3)
261-278: Well-documented type definitions for rawRequest.The
HttpMethodtype andClientRawRequestParamsinterface are clearly defined with JSDoc comments. This follows the existing patterns in the codebase.
967-1013: rawRequest method is well-implemented with excellent documentation.The method:
- Has comprehensive JSDoc with examples showing different use cases
- Properly delegates to the underlying API layer
- Uses
PromiseResult<any>which is appropriate for an escape hatch that can return arbitrary response data- Follows the existing patterns of other client methods
122-124: Minor formatting changes - no behavioral impact.These are just formatting adjustments to the existing type definitions.
api.ts (5)
811-849: rawRequest implementation follows SDK patterns correctly.The implementation:
- Uses the same URL construction pattern as other endpoints
- Properly handles query parameters via the existing
setSearchParamsutility- Only sets
Content-Type: application/jsonfor methods with body (POST/PUT/PATCH)- Uses
serializeDataIfNeededfor body serialization, consistent with other endpoints
1126-1143: OpenFgaApiFp rawRequest properly integrates with telemetry.The method correctly uses
createRequestFunctionwhich provides authentication, retry logic, and telemetry tracking. The telemetry attributeFgaClientRequestMethod: "RawRequest"is appropriately set for observability.
1344-1358: OpenFgaApiFactory rawRequest follows established patterns.The factory implementation correctly delegates to the functional programming interface.
1593-1608: OpenFgaApi class rawRequest method is well-documented.The public method has comprehensive JSDoc documentation and correctly delegates through the layers.
811-812: Path parameter is passed directly without validation.The
pathparameter is used directly in URL construction without validation. This is intentional for an "escape hatch" method, but consider documenting that:
- The path should start with
/- Path traversal characters could lead to unexpected behavior
This is acceptable given the method's purpose as an escape hatch for advanced users who know what they're doing.
Ensure the documentation or README mentions that users are responsible for constructing valid paths. The inline JSDoc example
'/stores/{store_id}/my-endpoint'provides good guidance.
|
Reposting my issue comment here:
|
SoulPancake
left a comment
SoulPancake
left a comment
There was a problem hiding this comment.
Thanks for the PR @Abishek-Newar
Can you add a section documenting this too
similar to the go-sdk https://github.com/openfga/go-sdk?tab=readme-ov-file#calling-other-endpoints
Examples should be nice to have
|
@SoulPancake I have made the reviewed changes |
|
Hi @SoulPancake , I’m seeing test case failures in the CI environment, but everything passes locally on my machine. |
|
@Abishek-Newar |
SoulPancake
changed the title
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #298 +/- ##
==========================================
+ Coverage 89.68% 90.00% +0.32%
==========================================
Files 25 25
Lines 1493 1531 +38
Branches 279 289 +10
==========================================
+ Hits 1339 1378 +39
- Misses 94 95 +1
+ Partials 60 58 -2 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
This PR introduces an “escape hatch” API on the JS SDK that allows sending arbitrary HTTP requests to OpenFGA endpoints while still using the SDK’s auth, retries, telemetry, and error handling.
Changes:
- Added a new
apiExecutormethod toOpenFgaApi/OpenFgaClientto build and execute arbitrary requests (method, path, body, query params, path params, telemetry operation name). - Added new client-facing types (
HttpMethod,ClientApiExecutorParams) for the new method. - Added a new Jest test suite for
apiExecutor, plus a README section describing how to call other endpoints.
Reviewed changes
Copilot reviewed 5 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
api.ts |
Adds apiExecutor request builder + FP/factory/class wiring to execute arbitrary endpoints. |
client.ts |
Exposes apiExecutor on OpenFgaClient with typed params and docs. |
tests/apiExecutor.test.ts |
New tests covering methods, query params, headers, errors, and path templating. |
README.md |
Documents how to call non-wrapped endpoints using apiExecutor. |
tests/helpers/index.ts |
Exports OPENFGA_STORE_ID from helpers. |
tests/helpers/nocks.ts |
Minor formatting fix at EOF. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
SoulPancake
left a comment
SoulPancake
left a comment
There was a problem hiding this comment.
Hi @Abishek-Newar, Any chances to address the comments? Thanks
|
Hii @SoulPancake , I have reverted the whitespace changes , other i am unable to detect it in my ide |
Description
This PR adds a rawRequest method to the SDK.
It allows developers to send any HTTP request to any OpenFGA API endpoint, while still using the SDK’s built-in features like authentication, configuration, retries, and error handling.
This is useful as an “escape hatch” for calling new or experimental API endpoints that don’t yet have official SDK methods.
The change adds rawRequest to both OpenFgaApi and OpenFgaClient, introduces new types (HttpMethod and ClientRawRequestParams), and includes a full test suite with 12 tests covering:
Closes #282
What problem is being solved?
Currently, the SDK provides typed methods for specific API endpoints (check, write, read, etc.). However, there is no way to call arbitrary OpenFGA API endpoints that may not yet have dedicated SDK methods. This creates a gap when:
New OpenFGA API endpoints are released but SDK updates have not been implemented yet
Experimental endpoints need to be tested
Developers need a temporary alternative while waiting for official SDK support
Without a raw request method, developers are forced to either wait for SDK updates, or fork and modify the SDK code themselves, or call the OpenFGA API directly without the SDK, losing the benefits of SDK authentication, configuration, and error handling patterns. This reduces developer agility and creates friction in adopting new OpenFGA features.
How is it being solved?
A new rawRequest method was added that takes an HTTP method, API path, and optional body and query parameters.
Internally, it uses the existing createRequestFunction, so it automatically handles:
This helps developers use new or experimental OpenFGA features quickly, while still following the same reliable patterns as the rest of the SDK.
What changes are made to solve it?
Added 12 tests covering all HTTP methods (GET, POST, PUT, DELETE, PATCH), query parameters, custom headers, authentication, and error handling.
References
Closes #282
Review Checklist
mainSummary by CodeRabbit
New Features
rawRequestmethod supports GET, POST, PUT, DELETE, and PATCH operations with custom bodies, query parameters, and headers.Tests