Choosing a REST Client
Juneau 10 ships two REST client stacks in the same release. Both are supported; they differ in which HTTP library they are built on and how much of the Juneau API surface they expose.
See the guide: Call an existing REST API with a typed proxy
juneau-rest-client (org.apache.juneau.rest.client.RestClient) is the recommended REST client. It is generally
available in 10.0.0, transport-agnostic, and uses the JDK HttpClient by default. juneau-rest-client-classic
(org.apache.juneau.rest.client.classic.RestClient, Apache HttpClient 4.5) stays supported and is not deprecated; it is
the stable choice for existing users. See Choosing a REST Client.
| Next-Generation (NG) client | Classic client | |
|---|---|---|
| Maven artifact | juneau-rest-client | juneau-rest-client-classic |
| Package | org.apache.juneau.rest.client | org.apache.juneau.rest.client.classic |
| HTTP library | Pluggable transport; JDK HttpClient by default (no third-party dependencies) | Apache HttpClient 4.5 only |
Extends HttpClient | No | Yes (implements org.apache.http.client.HttpClient) |
| HTTP types | org.apache.juneau.http.* | org.apache.juneau.http.classic.* (HttpCore-based) |
| Mock client | org.apache.juneau.rest.mock.MockRestClient | org.apache.juneau.rest.mock.classic.MockRestClient |
SSRF guard for @Remote / @Url | Yes, with per-hop redirect re-validation (NG Security) | Yes (classic guard classes) |
| Stability | Generally available in 10.0.0; the recommended client | Stable, unchanged from 9.x; supported, not deprecated |
Choose the NG client (juneau-rest-client) when...
- You are starting a new project.
- You want zero third-party dependencies (the JDK
HttpClienttransport is the default), or you want to pick OkHttp, Jetty, or Apache HttpClient 4.5/5 per deployment without changing application code. - You want the typed response accessors, assertions, and the
BodyConverterextension point. - You want serverless tests with the NG
MockRestClient.
Choose the classic client (juneau-rest-client-classic) when...
- You depend on
RestClientbeing an ApacheHttpClient(passing it to libraries that expect one, or customizing it throughHttpClientBuilder). - You have existing code that uses the classic fluent surface (
.json5(),.plainText(), etc.) and you cannot migrate yet. - You want the client unchanged from 9.x (stable and supported, not deprecated).
Existing 9.x code keeps working by changing imports to the .classic packages; the full rename table
is in the V10 Migration Guide.
Both in one project
The two clients can coexist in the same application, including both mock flavors (both live in the
juneau-rest-mock module). Migrate one call site at a time.
Where to go next
- NG client: overview, requests, responses, body converters, assertions, interceptors, security, transports.
- Classic client: juneau-rest-client basics.