Skip to content
Closed
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 72 additions & 69 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,8 @@ This is an autogenerated Java SDK for OpenFGA. It provides a wrapper around the
- [Assertions](#assertions)
- [Read Assertions](#read-assertions)
- [Write Assertions](#write-assertions)
- [Retries](#retries)
- [Calling Other Endpoints](#calling-other-endpoints)
- [Retries](#retries)
- [API Endpoints](#api-endpoints)
- [Models](#models)
- [OpenTelemetry](#opentelemetry)
Expand Down Expand Up @@ -1114,74 +1114,6 @@ fgaClient.writeAssertions(assertions, options).get();
```


### Retries

The SDK implements RFC 9110 compliant retry behavior with support for the `Retry-After` header. By default, the SDK will automatically retry failed requests up to **3 times** with delay calculation (maximum allowable: 15 retries).

#### Retry Behavior

**Rate Limiting (429 errors):** Always retried regardless of HTTP method.

**Server Errors (5xx):** All requests are retried on 5xx errors (except 501 Not Implemented) regardless of HTTP method:
- **All operations** (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS): Always retried on 5xx errors with delay calculation

#### Delay Calculation

1. **Retry-After header present**: Uses the server-specified delay (supports both integer seconds and HTTP-date formats)
2. **No Retry-After header**: Uses exponential backoff with jitter (base delay: 2^retryCount * 100ms, capped at 120 seconds)
3. **Minimum delay**: Respects the configured `minimumRetryDelay` as a floor value

#### Configuration

Customize retry behavior using the `ClientConfiguration` builder. The SDK enforces a maximum of 15 retries to prevent accidental server overload:

**⚠️ Breaking Changes:**
- Configuration validation now prevents setting `maxRetries` above 15
- `FgaError` now exposes the `Retry-After` header value via `getRetryAfterHeader()`

```java
import com.fasterxml.jackson.databind.ObjectMapper;
import dev.openfga.sdk.api.client.OpenFgaClient;
import dev.openfga.sdk.api.configuration.ClientConfiguration;
import java.net.http.HttpClient;

public class Example {
public static void main(String[] args) throws Exception {
var config = new ClientConfiguration()
.apiUrl(System.getenv("FGA_API_URL")) // If not specified, will default to "http://localhost:8080"
.storeId(System.getenv("FGA_STORE_ID")) // Not required when calling createStore() or listStores()
.authorizationModelId(System.getenv("FGA_MODEL_ID")) // Optional, can be overridden per request
.maxRetries(3) // retry up to 3 times on API requests (default: 3, maximum: 15)
.minimumRetryDelay(Duration.ofMillis(100)); // minimum wait time between retries in milliseconds (default: 100ms)

var fgaClient = new OpenFgaClient(config);
var response = fgaClient.readAuthorizationModels().get();
}
}
```

#### Error Handling with Retry Information

When handling errors, you can access the `Retry-After` header value for debugging or custom retry logic:

```java
try {
var response = fgaClient.check(request).get();
} catch (ExecutionException e) {
if (e.getCause() instanceof FgaError) {
FgaError error = (FgaError) e.getCause();

// Access Retry-After header if present
String retryAfter = error.getRetryAfterHeader();
if (retryAfter != null) {
System.out.println("Server requested retry after: " + retryAfter + " seconds");
}

System.out.println("Error: " + error.getMessage());
}
}
```

### Calling Other Endpoints

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.
Expand Down Expand Up @@ -1288,6 +1220,77 @@ For a complete working example, see [examples/api-executor](examples/api-executo
See [docs/ApiExecutor.md](docs/ApiExecutor.md) for complete API reference and examples for both `ApiExecutor` and `StreamingApiExecutor`.



### Retries

The SDK implements RFC 9110 compliant retry behavior with support for the `Retry-After` header. By default, the SDK will automatically retry failed requests up to **3 times** with delay calculation (maximum allowable: 15 retries).

#### Retry Behavior

**Rate Limiting (429 errors):** Always retried regardless of HTTP method.

**Server Errors (5xx):** All requests are retried on 5xx errors (except 501 Not Implemented) regardless of HTTP method:
- **All operations** (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS): Always retried on 5xx errors with delay calculation

#### Delay Calculation

1. **Retry-After header present**: Uses the server-specified delay (supports both integer seconds and HTTP-date formats)
2. **No Retry-After header**: Uses exponential backoff with jitter (base delay: 2^retryCount * 100ms, capped at 120 seconds)
3. **Minimum delay**: Respects the configured `minimumRetryDelay` as a floor value

#### Configuration

Customize retry behavior using the `ClientConfiguration` builder. The SDK enforces a maximum of 15 retries to prevent accidental server overload:

**⚠️ Breaking Changes:**
- Configuration validation now prevents setting `maxRetries` above 15
- `FgaError` now exposes the `Retry-After` header value via `getRetryAfterHeader()`

```java
import com.fasterxml.jackson.databind.ObjectMapper;
import dev.openfga.sdk.api.client.OpenFgaClient;
import dev.openfga.sdk.api.configuration.ClientConfiguration;
import java.net.http.HttpClient;

public class Example {
public static void main(String[] args) throws Exception {
var config = new ClientConfiguration()
.apiUrl(System.getenv("FGA_API_URL")) // If not specified, will default to "http://localhost:8080"
.storeId(System.getenv("FGA_STORE_ID")) // Not required when calling createStore() or listStores()
.authorizationModelId(System.getenv("FGA_MODEL_ID")) // Optional, can be overridden per request
.maxRetries(3) // retry up to 3 times on API requests (default: 3, maximum: 15)
.minimumRetryDelay(Duration.ofMillis(100)); // minimum wait time between retries in milliseconds (default: 100ms)

var fgaClient = new OpenFgaClient(config);
var response = fgaClient.readAuthorizationModels().get();
}
}
```

#### Error Handling with Retry Information

When handling errors, you can access the `Retry-After` header value for debugging or custom retry logic:

```java
try {
var response = fgaClient.check(request).get();
} catch (ExecutionException e) {
if (e.getCause() instanceof FgaError) {
FgaError error = (FgaError) e.getCause();

// Access Retry-After header if present
String retryAfter = error.getRetryAfterHeader();
if (retryAfter != null) {
System.out.println("Server requested retry after: " + retryAfter + " seconds");
}

System.out.println("Error: " + error.getMessage());
}
}
```



### API Endpoints

| Method | HTTP request | Description |
Expand Down
Loading