https://github.com/openfacade/http-facade
Simple Http Client/Server Facade for Java
https://github.com/openfacade/http-facade
facade http http-client http-server java
Last synced: 6 months ago
JSON representation
Simple Http Client/Server Facade for Java
- Host: GitHub
- URL: https://github.com/openfacade/http-facade
- Owner: openfacade
- License: apache-2.0
- Created: 2024-09-13T09:46:54.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-06T07:35:39.000Z (6 months ago)
- Last Synced: 2025-04-15T02:54:12.832Z (6 months ago)
- Topics: facade, http, http-client, http-server, java
- Language: Java
- Homepage: https://github.com/openfacade
- Size: 221 KB
- Stars: 6
- Watchers: 1
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# HTTP Facade
  [](https://github.com/openfacade/http-facade/releases) [](https://codecov.io/gh/openfacade/http-facade)
English | [简体中文](README_CN.md)
`HTTP Facade` is a flexible Java library that provides a unified API for both HTTP clients and HTTP servers(WIP). The library supports multiple underlying implementations (e.g., OkHttp, AsyncHttpClient for clients) and provides easy configuration of HTTP requests and responses, connection timeouts, TLS settings, routing, and more.
## Why Use a Facade Library?
The `HTTP Facade` library offers a streamlined approach for integrating multiple HTTP client implementations within a single application.
By providing a unified API, it abstracts the complexities of various HTTP engines (such as `OkHttp` or `AsyncHttpClient`) while allowing easy configuration of essential features like request timeouts, TLS settings.
In many integration scenarios, applications based on HTTP libraries may need to adapt to specific requirements.
For instance, some embedded environments prioritize smaller footprint sizes, Android applications require platform-specific compatibility, and other cases may demand high performance and low latency.
In these situations, using a thin facade layer can be highly advantageous, allowing developers to meet diverse needs without rewriting core logic or managing multiple client libraries.
Instead, `HTTP Facade` enables easy switching between implementations, ensuring consistency, simplicity, and enhanced maintainability across various use cases.
## HttpClientFacade
### HttpClient Support Engines
- [**AsyncHttpClient**](https://github.com/AsyncHttpClient/async-http-client)
- **JavaHttpClient**: Java11+ built-in HTTP client
- **Java8HttpClient**: Java8 built-in HTTP client
- [**JettyHttpClient**](https://github.com/jetty/jetty.project)
- [**OkHttpClient**](https://github.com/square/okhttp)
- [**VertxHttpClient**](https://github.com/vert-x3/vertx-web)
### Installation
By default, the `HttpClientFacade` uses the built-in HTTP engine provided by the JDK. It automatically selects the appropriate implementation based on the Java version, supporting both Java 8 and Java 11+. However, if you wish to use a specific HTTP engine like `OkHttp` or `AsyncHttpClient`, you'll need to add the corresponding dependencies.
#### Maven
Add the following dependency to your `pom.xml` to include the default `http-facade`:
```xml
io.github.openfacade
http-facade
${http-facade.version}
```
If you'd like to use a specific HTTP engine, you need to add additional dependencies:
- **ApacheHttpClient**:
```xml
io.github.openfacade
http-facade
${http-facade.version}
org.apache.httpcomponents.client5
httpclient5
${apache-http-client.version}
```
- **AsyncHttpClient**:
```xml
io.github.openfacade
http-facade
${http-facade.version}
org.asynchttpclient
async-http-client
${asynchttp.version}
```
- **Jetty**:
```xml
io.github.openfacade
http-facade
${http-facade.version}
org.eclipse.jetty
jetty-client
${jetty.version}
```
- **OkHttp**:
```xml
io.github.openfacade
http-facade
${http-facade.version}
com.squareup.okhttp3
okhttp
${okhttp.version}
```
- **Vertx**:
```xml
io.github.openfacade
http-facade
${http-facade.version}
io.vertx
vertx-web-client
${vertx.version}
```
#### Gradle
For Gradle users, add the default `http-facade` dependency:
```groovy
implementation 'io.github.openfacade:http-facade-client:$httpFacadeVersion'
```
To specify an HTTP engine, need to add dependencies:
- **ApacheHttpClient**:
```groovy
implementation 'io.github.openfacade:http-facade-client-okhttp:$httpFacadeVersion'
implementation 'org.apache.httpcomponents.client5:httpclient5:$apacheHttpClientVersion}'
```
- **AsyncHttpClient**:
```groovy
implementation 'io.github.openfacade:http-facade-client-okhttp:$httpFacadeVersion'
implementation 'org.asynchttpclient:async-http-client:$asynchttpVersion'
```
- **Jetty**:
```groovy
implementation 'io.github.openfacade:http-facade-client-okhttp:$httpFacadeVersion'
implementation 'org.eclipse.jetty:jetty-client:$jettyVersion'
```
- **OkHttp**:
```groovy
implementation 'io.github.openfacade:http-facade-client-okhttp:$httpFacadeVersion'
implementation 'com.squareup.okhttp3:okhttp:$okhttpVersion'
```
- **Vertx**:
```groovy
implementation 'io.github.openfacade:http-facade-client-okhttp:$httpFacadeVersion'
implementation 'io.vertx:vertx-web-client:$vertxVersion'
```
### Getting Started
#### 1. Create a Configuration
First, create a `HttpClientConfig` to configure timeouts and TLS settings.
```java
HttpClientConfig config = new HttpClientConfig.Builder()
.engine(HttpClientEngine.OKHTTP) // Choose the engine (e.g., OKHTTP, ASYNC_HTTP_CLIENT, JDK)
.timeout(Duration.ofSeconds(30)) // Set request timeout
.connectTimeout(Duration.ofSeconds(10)) // Set connection timeout
.build();
```
#### 2. Create a Client
Use the `HttpClientFactory` to create the desired client instance with the above configuration.
```java
HttpClient client = HttpClientFactory.createHttpClient(config);
```
#### 3. Make HTTP Requests
##### Asynchronous Requests
```java
CompletableFuture future = client.get("http://example.com", Map.of());
future.thenAccept(response -> {
System.out.println("Status: " + response.getStatusCode());
System.out.println("Body: " + new String(response.getBody()));
});
```
##### Synchronous Requests
```java
HttpResponse response = client.getSync("http://example.com", Map.of());
System.out.println("Status: " + response.getStatusCode());
System.out.println("Body: " + new String(response.getBody()));
```
#### 4. Close the Client
Remember to close the client when you're done to release any resources.
```java
client.close();
```