NG Requests

A request is built fluently from a RestClient verb method and executed with run(). Each verb (get, post, put, patch, delete, head, and request(method, url)) returns a RestRequest.

RestClient client = RestClient.builder()
    .rootUrl("https://api.example.com")
    .serializer(Json5Serializer.create().build())
    .parser(Json5Parser.create().build())
    .build();

try (var resp = client.post("/users/{id}/notes")
        .pathData("id", 42)
        .queryData("notify", true)
        .header("X-Trace", "abc")
        .body(new Note("hello"))
        .timeout(Duration.ofSeconds(5))
        .run()) {
    resp.assertOk();
}

Request parts

Method	Purpose
header(name, value) / headers(...)	Request headers.
queryData(name, value)	Query-string parameters.
formData(name, value)	application/x-www-form-urlencoded form fields.
pathData(name, value)	Substitutes {name} in the URL path.
timeout(Duration)	Per-request timeout.
requestId(String)	Overrides the generated X-Request-Id.

Defaults set on the builder (header, headers, queryData) apply to every request made by that client.

Request bodies

Method	Behavior
body(HttpBody)	Sent as-is.
body(Object)	Runs the body converter chain first (HttpBody, InputStream, byte[], File, plus any you registered); if none matches, the object is serialized with the client's default serializer. With no default serializer configured, an IllegalStateException is thrown.
bodyString(String)	Sent as text/plain.
streamBodyEntity(RecordStreamBody)	Streams a record sequence without buffering it. See Streaming Cursors.

Running the request

run() sends the request and returns a RestResponse. Transport-level failures (DNS, connect, TLS, I/O) throw TransportException. HTTP error statuses do not throw unless you ask for it with assertOk(), assertStatus(int), or throwOnError on a remote proxy; those throw RestCallException, which carries getStatusCode().

openEventStream() runs the request and returns the response as a server-sent event stream.

Per-request interceptors and URL policy

interceptors(...) adds interceptors for this request only.

remoteUrlPolicy(boolean enforced, boolean allowPrivateUrls) controls the SSRF guard for a single request. Ordinary client.get(url) calls are not policy-covered by default; @Remote and @Url calls are. See NG Security.

Builder options

Builder method	Purpose
transport(HttpTransport)	Explicit transport; otherwise auto-discovered.
rootUrl(String)	Prefix for relative request URLs.
header(s), queryData	Defaults for every request.
serializer(s), parser(s)	Marshalling. defaultSerializer / defaultParser choose the one used when several are registered.
bodyConverter(s)	Body converters.
interceptors(...)	Interceptors.
allowPrivateUrls(boolean)	Opt out of the private-address deny-list for policy-covered calls.
sendRequestId(boolean)	Toggles the automatic X-Request-Id header (on by default).
debugFormatter, debugLoggerName	See Logging and Debugging.

client.remote(MyApi.class) creates a remote proxy that uses this same client.