Skip to content

docs: document UriUtils.encodePath for Java client service invocation #5231

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
javier-aliaga wants to merge 3 commits into
base: v1.18
Choose a base branch
from
Open

docs: document UriUtils.encodePath for Java client service invocation #5231

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9e9fc03
docs: document UriUtils.encodePath for Java client service invocation
javier-aliaga Jul 1, 2026
ceef976
docs: address review feedback on path-encoding section
javier-aliaga Jul 2, 2026
096b4b7
Merge branch 'v1.18' into docs/java-invoke-http-path-encoding
javier-aliaga Jul 6, 2026
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
13 changes: 13 additions & 0 deletions sdkdocs/java/content/en/java-sdk-docs/java-client/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,18 @@ try (DaprClient client = new DaprClientBuilder().build()) {

`DaprBodyPublishers.json(...)` serializes the payload using the SDK's default Jackson serializer, matching the JSON encoding the deprecated `invokeMethod` APIs applied internally. For raw payloads use any `HttpRequest.BodyPublisher` (for example `HttpRequest.BodyPublishers.ofString(...)`).

`newRequestBuilder(relativePath)` resolves the path as-is without encoding it for you. If a path segment may contain characters that are illegal in a URI (for example spaces), encode it first with `io.dapr.utils.UriUtils.encodePath(...)` method. Without this encoding, passing such characters directly throws an `IllegalArgumentException`. The `encodePath` method percent-encodes each forward-slash delimited segment (`/`), preserving the separators and any leading slashes, and appends the query string unchanged. This behavior mirrors the per-segment encoding that the deprecated `invokeMethod` APIs applied automatically:

```java
import io.dapr.utils.UriUtils;

// "Name With Spaces" -> "Name%20With%20Spaces"
HttpRequest request = invoker.newRequestBuilder(
UriUtils.encodePath("orders/Name With Spaces"))
.GET()
.build();
```

The table below summarizes which concerns `DaprInvokeHttpClient` handles for you (when configured with `DaprClientBuilder`) and which belong to the user:

| Concern | Handled by the SDK | User's responsibility |
Expand All @@ -94,6 +106,7 @@ The table below summarizes which concerns `DaprInvokeHttpClient` handles for you
| `dapr-api-token` header | ✓ — attached only when configured via the `dapr.api.token` system property or `DAPR_API_TOKEN` environment variable | |
| HTTP read timeout | ✓ — defaults to **60 seconds**; override via the `dapr.http.client.readTimeoutSeconds` system property or `DAPR_HTTP_CLIENT_READ_TIMEOUT_SECONDS` environment variable | |
| `User-Agent: dapr-sdk-java/<version>` header | ✓ — value tracks the SDK version automatically | |
| URL path encoding | | Encode path segments that may contain characters illegal in a URI (e.g. spaces) with `UriUtils.encodePath(...)`. The `newRequestBuilder` method resolves the path unchanged and throws `IllegalArgumentException` on illegal characters. |
| `Content-Type` header | | Set via `.header("Content-Type", "...")` |
| Request body serialization | | Use `DaprBodyPublishers.json(...)` for default JSON, or any `HttpRequest.BodyPublisher` |
| Response body deserialization | | Pick an `HttpResponse.BodyHandler` (`ofString`, `ofByteArray`, custom) |
Expand Down
Loading