{"id":22093396,"url":"https://github.com/nstdio/http-client-ext","last_synced_at":"2025-10-12T00:31:55.426Z","repository":{"id":38235401,"uuid":"403128821","full_name":"nstdio/http-client-ext","owner":"nstdio","description":"Extensions to JDK's HttpClient","archived":false,"fork":false,"pushed_at":"2025-01-25T20:40:13.000Z","size":1181,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-25T21:21:38.777Z","etag":null,"topics":["cache","gzip","http","java","json"],"latest_commit_sha":null,"homepage":"","language":"Kotlin","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nstdio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-09-04T18:26:38.000Z","updated_at":"2025-01-25T20:32:47.000Z","dependencies_parsed_at":"2023-11-18T15:09:31.553Z","dependency_job_id":"d03a1591-4229-46af-9500-712c0e55b4a2","html_url":"https://github.com/nstdio/http-client-ext","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nstdio%2Fhttp-client-ext","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nstdio%2Fhttp-client-ext/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nstdio%2Fhttp-client-ext/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nstdio%2Fhttp-client-ext/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nstdio","download_url":"https://codeload.github.com/nstdio/http-client-ext/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236142736,"owners_count":19101664,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","gzip","http","java","json"],"created_at":"2024-12-01T03:14:25.022Z","updated_at":"2025-10-12T00:31:49.783Z","avatar_url":"https://github.com/nstdio.png","language":"Kotlin","readme":"# HttpClient Extensions\n\nThe project provides useful extensions to\nJDK's [HttpClient](https://docs.oracle.com/en/java/javase/11/docs/api/java.net.http/java/net/http/HttpClient.html).\n\n### Status\n| Type          | Status                                                                                                                                                                                                                                                                                                                                                       |\n|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Build         | [![Build](https://github.com/nstdio/http-client-ext/actions/workflows/build.yaml/badge.svg)](https://github.com/nstdio/http-client-ext/actions/workflows/build.yaml)                                                                                                                                                                                         |\n| Artifact      | [![Maven Central](https://img.shields.io/maven-central/v/io.github.nstdio/http-client-ext.svg?label=Maven%20Central)](https://search.maven.org/search?q=g:%22io.github.nstdio%22%20AND%20a:%22http-client-ext%22)                                                                                                                                            |\n| Javadoc       | [![javadoc](https://javadoc.io/badge2/io.github.nstdio/http-client-ext/javadoc.svg)](https://javadoc.io/doc/io.github.nstdio/http-client-ext)                                                                                                                                                                                                                |\n| Code coverage | [![codecov](https://codecov.io/gh/nstdio/http-client-ext/branch/main/graph/badge.svg)](https://codecov.io/gh/nstdio/http-client-ext)                                                                                                                                                                                                                         |\n| LGTM          | [![Total alerts](https://img.shields.io/lgtm/alerts/g/nstdio/http-client-ext.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/nstdio/http-client-ext/alerts/) [![Language grade: Java](https://img.shields.io/lgtm/grade/java/g/nstdio/http-client-ext.svg?logo=lgtm\u0026logoWidth=18)](https://lgtm.com/projects/g/nstdio/http-client-ext/context:java) |\n\n### Requirements\n\n- Java 11+ \n- [Gradle](https://gradle.org/) for building the project.\n\n### Gradle\n\n```\nimplementation 'io.github.nstdio:http-client-ext:2.4.0'\n```\n\n### Maven\n\n```\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.nstdio\u003c/groupId\u003e\n    \u003cartifactId\u003ehttp-client-ext\u003c/artifactId\u003e\n    \u003cversion\u003e2.4.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n### Features\n\n- [Caching](#Caching), both in memory and disk.\n- [Decompression](#Decompression): `br, zstd, gzip, deflate`\n- [JSON](#JSON) mappings\n\n### Caching\n\nThe `ExtendedHttpClient` implements client part of [RFC7234](https://datatracker.ietf.org/doc/html/rfc7234)\n\nThere are two types of cache:\n```\n// backed by volotile in-memory storage\nCache mem = Cache.newInMemoryCacheBuilder().build()\n\n// and persistent storage\nCache disk = Cache.newDiskCacheBuilder().dir(Path.of(\"...\")).build()\n```\n\nHere is the example of creating client with in memory cache:\n\n```java\nHttpClient client = ExtendedHttpClient.newBuilder()\n        .cache(Cache.newInMemoryCacheBuilder().build())\n        .build();\n\nURI uri = URI.create(\"https://api.github.com/users/defunkt\");\nHttpRequest request = HttpRequest.newBuilder(uri).build();\n\nHttpResponse\u003cString\u003e networkResponse = client.send(request, ofString());\nHttpResponse\u003cString\u003e cachedResponse = client.send(request, ofString());\n```\n\nand all available configurations for in memory cache:\n\n```java\nCache inMemory = Cache.newInMemoryCacheBuilder()\n        .maxItems(4096) // number of responses can be cached\n        .size(10 * 1000 * 1000) // maximum size of the entire cache in bytes, -1 for no constraint\n        .requestFilter(request -\u003e request.uri().getHost().equals(\"api.github.com\")) // cache only requests that match given predicate\n        .responseFilter(response -\u003e response.statusCode() == 200) // cache only responses that match given predicate\n        .build();\n```\n\nAbove-mentioned configurations also applies to persistent cache with some additions\n\n```java\nPath cacheDir = ...\nCache disk = Cache.newDiskCacheBuilder()\n        .dir(cacheDir)\n        .build();        \n```\nIf request/response contains sensitive information one might want to store it encrypted:\n\n```java\nPath cacheDir = ...\nSecretKey secretKey = ...\n\nCache encrypted = Cache.newDiskCacheBuilder()\n        .dir(cacheDir)\n        .encrypted()\n        .key(secretKey)\n        .cipherAlgorithm(\"AES\")\n        .build();\n```\nwill create persistent cache which encrypts data by user provided key.\n\n### Decompression\nHere is an example of transparent encoding feature\n\n```java\nHttpClient client = ExtendedHttpClient.newBuilder()\n        .transparentEncoding(true)\n        .build();\n\nURI uri = URI.create(\"https://api.github.com/users/defunkt\");\nHttpRequest request = HttpRequest.newBuilder(uri).build();\n\n// Client will add `Accept-Encoding: gzip, deflate` header to the request\n// then decompress response body transparently of the user        \nHttpResponse\u003cString\u003e response = client.send(request, ofString());\n```\n\nthere is also dedicated `BodyHandler` for that, but in this case user should add `Accept-Encoding` header manually\n\n```java\nHttpClient client = HttpClient.newClient();\n\nURI uri = URI.create(\"https://api.github.com/users/defunkt\");\nHttpRequest request = HttpRequest.newBuilder(uri)\n        .header(\"Accept-Encoding\", \"gzip, deflate\")\n        .build();\n\nHttpResponse\u003cString\u003e response = client.send(request, BodyHandlers.ofDecompressing(ofString()));\n```\nOut of the box support for `gzip` and `deflate` is provided by JDK itself. For `br` (brotli) or `zstd` compression\nplease add one of following dependencies to your project:\n\n- [org.brotli:dec](https://mvnrepository.com/artifact/org.brotli/dec/0.1.2)\n- [Brotli4j](https://github.com/hyperxpro/Brotli4j)\n- [zstd-jni](https://github.com/luben/zstd-jni)\n\nservice loader will pick up correct dependency. If none of these preferred there is always an options to extend via [SPI](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/ServiceLoader.html)\nby providing [CompressionFactory](https://github.com/nstdio/http-client-ext/blob/main/src/main/java/io/github/nstdio/http/ext/spi/CompressionFactory.java)\n\n### JSON\nCurrently, two libraries are supported\n\n- [Jackson](https://github.com/FasterXML/jackson-databind)\n- [Gson](https://github.com/google/gson)\n\njust drop one of them as dependency and voilà\n\n```java\n// will create object using Jackson or Gson\nUser user = client.send(request, BodyHandlers.ofJson(User.class));\n\n// or send JSON\nObject user = null;\nHttpRequest request = HttpRequest.newBuilder()\n  .uri(URI.create(\"https://example.com/users\"))\n  .POST(BodyPublishers.ofJson(user))\n  .build();\n\nExtendedHttpClient client = ExtendedHttpClient.newHttpClient();\nHttpResponse\u003cUser\u003e response = client.send(request, BodyHandlers.ofJson(User.class));\n```\n\nAnd if special configuration required\n```java\npackage com.example;\n\nclass JacksonMappingProvider implements JsonMappingProvider {\n  @Override\n  public JsonMapping get() {\n    // configure jackson\n    ObjectMapper mapper = ...\n\n    return new JacksonJsonMapping(mapper);\n  }\n}\n```\nthen  standard SPI registration can be used or custom provider can be registered manually:\n\n```java\nJacksonMappingProvider jackson = ...\n\nJsonMappingProvider.addProvider(jackson);\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnstdio%2Fhttp-client-ext","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnstdio%2Fhttp-client-ext","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnstdio%2Fhttp-client-ext/lists"}