Apache HttpClient 5 is a mirror, a Maven multi-module and an export notice

This repository is a mirror, so watch who merges it

The repository description says it plainly: this is a mirror of Apache HttpClient. That single line changes how you should read everything else.

Apache Software Foundation projects keep their canonical history in an Apache-controlled repository and mirror outward to GitHub so people can read and clone the code. The practical consequence is that commits here arrive from the ASF side. Opening a pull request against the mirror is not how you contribute, and the README routes that elsewhere.

The contact section names three destinations with different purposes: the main project site at hc.apache.org for general information, a status page at hc.apache.org/status.html for current status, and a get-involved page for contributions.

The repository carries the ASF governance files you would expect, including CODE_OF_CONDUCT.md, SECURITY.md, RELEASE_NOTES.txt and the `doap_HttpComponents_Client.rdf` file that describes the project for ASF infrastructure. A `.asf.yaml` file at the root is the same idea in machine-readable form.

For an evaluator this matters. The absence of GitHub releases is not neglect: releases are cut by the ASF, not here. But it does mean you should look at the Maven Central coordinates rather than the releases page of this mirror when you decide what version to use.

Nine modules, and the extras are the reason to choose it

The top level of the repository is where the module structure becomes visible, and it is the clearest statement of what this library actually covers.

The core is `httpclient5/`. Around it sit six feature modules plus a testing module: `httpclient5-cache/`, `httpclient5-fluent/`, `httpclient5-jakarta-rest-client/`, `httpclient5-observation/`, `httpclient5-sse/`, `httpclient5-testing/` and `httpclient5-websocket/`.

Each answers a different gap. The cache module implements the HTTP caching semantics rather than leaving you to write them, which is the piece most often reimplemented badly in application code. The fluent module is a builder-style API for constructing requests without setters. The Jakarta REST client module targets application code already written against Jakarta REST rather than against the low-level client. Server-sent events and WebSocket are transports the core module does not handle, and there is a dedicated module for each.

The observation module is the one worth pausing on. Instrumenting an HTTP client so that timings and traces reach your metrics backend is work nobody should do per application, and having it as an official module means the metrics come out in a shape the project controls.

The testing module is for people verifying their own interceptors and mocks against the real implementation, which is a good sign about how the project expects clients to be tested.

The structure implies you take only what you use. The core module's external dependencies are deliberately minimal, so an application that needs nothing but HTTP/1.1 does not inherit caching or WebSocket code.

HttpCore and SLF4J are the whole mandatory dependency list

The dependency section is short and it is worth reading as design intent.

The main module requires a Java 8 compatible runtime and depends on two external libraries: Apache HttpComponents HttpCore and the SLF4J API. Everything else is described as optional, with pom.xml holding the detail.

SLF4J being mandatory tells you logging goes through the facade rather than being baked in, so an application chooses its binding and HttpClient does not drag one along. That is the difference between a library that logs to stderr by default and one that fits your existing log pipeline.

HttpCore carries the protocol-level pieces that the client layer builds on. Splitting it this way means code that only needs to construct or parse a request line and headers does not pull the full client.

The Java 8 floor is the other thing to note. It is what makes the library usable in long-lived server deployments that have not moved their runtime, and it also constrains which language features you will see in the code.

Because the mandatory set is this small, the cost of choosing this library over the one in your JDK is dominated by the modules you add rather than by the core.

The RFC list is a better feature list than the README

Instead of prose describing what the client supports, the README enumerates the specifications it implements. That list is unusually current and it is the fastest way to judge fit.

The core semantics come from RFC 9110 for HTTP Semantics, RFC 9111 for HTTP Caching, RFC 9112 for HTTP/1.1 and RFC 9113 for HTTP/2. Header compression is RFC 7541, HPACK. RFC 1945 covers HTTP/1.0, and RFC 3986 covers URI generic syntax.

Authentication is broad: RFC 7617 for Basic, RFC 7616 for Digest, and RFC 7804 for the Salted Challenge Response mechanism. Cookies are RFC 6265, caching of stale content is RFC 5861, and upgrading from HTTP/1.1 to TLS is RFC 2817.

Then the newer transport work. RFC 9218 covers Extensible Prioritizing Scheme for HTTP, RFC 7639 covers the ALPN header field, and RFC 10008 covers the HTTP QUERY method. WebSocket support is RFC 6455, its permessage-deflate compression is RFC 7692, and bootstrapping WebSocket over HTTP/2 is RFC 8441.

Three of those are worth pausing on for a Java engineer. The QUERY method means the client can send an HTTP QUERY request, which is still uncommon outside this ecosystem. RFC 8441 means WebSocket connections can be established over an HTTP/2 connection rather than being limited to HTTP/1.1 upgrades. And the prioritization scheme matters if you are multiplexing several requests over one connection and need to control what goes first.

The list is also a maintenance signal. These are the current RFC numbers rather than the old ones, which means the project tracks the specifications as they are revised.

Building uses a Maven wrapper and a bundled test CA

Build instructions are not in the README. They are delegated to a separate file, BUILDING.txt, which is the normal arrangement for an ASF component and is where you should look before configuring anything.

The repository includes `mvnw` and `mvnw.cmd`, so the Maven wrapper is checked in. That is the practical reason you do not need a matching Maven installation on your machine, and it is what CI uses as well.

Two other entries deserve attention. There is a `run-example.sh` script at the root, and there is a `test-CA/` directory, which is a test certificate authority. The presence of a test CA is the interesting one: TLS behaviour cannot be tested against a public certificate authority without hitting the network, so a client library with a meaningful test suite needs to generate and trust its own certificates. That also means you will find TLS handshake behaviour exercised locally, which is where the majority of client bugs actually appear.

The Maven Central coordinate is visible in the badge in the README, `org.apache.httpcomponents.client5` with artifact `httpclient5`, and the CI badge shows the Java CI workflow.

There is no GitHub release page to consult for versions. The project's release history lives in RELEASE_NOTES.txt and in the ASF distribution, which is where you should look before upgrading a major version.

The export classification is part of adopting this

Most READMEs do not carry a cryptographic software notice. This one does, and it makes specific claims that your organisation may need.

The notice states that the software has been classified by the US Department of Commerce Bureau of Industry and Security under Export Commodity Control Number 5D002.C.1, which covers information security software performing cryptographic functions with asymmetric algorithms. It then states that the form of this ASF distribution makes it eligible for export under the License Exception ENC Technology Software Unrestricted, for both object code and source code, citing Section 740.13 of the Export Administration Regulations.

The practical reading is that the classification is acknowledged and the exception is what removes the friction, so you should be able to use it without a licence exception application of your own. That said, this is a compliance question rather than a technical one, and if your company tracks export classifications, note the ECCN number so your records match.

The technical counterpart of the notice is just as informative. Apache HttpClient interfaces with the Java Secure Socket Extension, the JSSE API, to provide HTTPS support, and the README states plainly that it does not include any implementation of JSSE. TLS is the JDK's job; this library handles the HTTP on top of it.

That division has a consequence worth knowing. Behaviour you might expect the client to control, such as which TLS versions or cipher suites are offered, is configured in your JVM and in your HTTP client configuration, and a client-side default will not override the platform.

Where Apache HttpClient is the wrong choice

Three cases.

For a plain GET or POST, compare the dependency and maintenance cost of an additional library with the HTTP facilities already available in your stack.

If you need caching or a fluent API or WebSocket, the comparison flips. Those are real modules with real maintenance behind them, and reimplementing HTTP caching semantics correctly is not a good use of a sprint.

If your application is already built on Jakarta REST, the `httpclient5-jakarta-rest-client` module exists for that case and using the raw core client inside a JAX-RS or Jakarta REST stack will fight the framework's own configuration.

The licensing is Apache License 2.0, and the README points to LICENSE.txt and NOTICE.txt for the actual terms. Apache-2.0 is permissive for commercial and closed-source use, with the usual obligation to preserve notices, and it carries an explicit patent grant, which is the part most relevant when you are building commercial software on top of it.

Editorial conclusion

Adopt Apache HttpClient 5 when you need response caching, WebSocket or the Jakarta REST client, and stay on the Maven artifact `org.apache.httpcomponents.client5:httpclient5` rather than tracking this mirror. Skip it for a plain HTTP/2 GET where the built-in Java client is enough. Verify first which modules you pull in, since each extra module is an extra dependency, and confirm your Java runtime meets the stated Java 8 compatible floor.

Frequently asked questions

Official sources

1. apache/httpcomponents-client on GitHub
2. Issues
3. License: Apache-2.0
4. README