README.md

Requestor

A simple and zero dependency way to make http requests in Java

requestor is a single-file wrapper around the standard Java 11 HttpClient. It got quite monotonous writing the same boilerplate code in every side project and script, so I made this as others probably do it too. It provides something like Python's requests library without adding heavy third-party dependencies like Apache HttpClient and OkHttp.

The standard way we do it (Verbose)

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.example.com"))
    .header("Accept", "application/json")
    .GET()
    .build();

try {
    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
} catch (Exception e) {
    e.printStackTrace();
}

The requestor way

System.out.println(Requestor.get("https://api.example.com").send().text());

Installation

Option 1: Maven

<dependency>
    <groupId>dev.turan</groupId>
    <artifactId>requestor</artifactId>
    <version>1.0.0</version>
</dependency>

Option 2: Gradle

implementation 'dev.turan:requestor:1.0.0'

Option 3: Copy and Paste

It's a single file, you can copy it directly into your project if you want to avoid managing another artifact.

1. Copy Requestor.java
2. Change the package to match your project.

Usage

Simple GET

String html = Requestor.get("https://example.com").send().text();

POST with JSON

String json = "{\"name\": \"John\", \"age\": 30}";

Requestor.Response response = Requestor.post("https://httpbin.org/post")
    .header("Content-Type", "application/json")
    .body(json)
    .send();

System.out.println(response.status()); // 200

Authentication (Basic & Bearer)

// Basic Auth
Requestor.get("https://api.example.com")
    .auth("username", "password")
    .send();

// Bearer Token
Requestor.get("https://api.example.com/v1/me")
    .auth("my-access-token-123")
    .send();

OAuth 2.0 (Client Credentials)

The library includes a helper to fetch OAuth tokens without parsing JSON manually.

// 1. Fetch the token
String token = Requestor.fetchToken("https://auth.example.com/token", "CLIENT_ID", "CLIENT_SECRET");

// 2. Use the token
Requestor.get("https://api.server.com/users")
       .auth(token)
       .send();

File Upload

Requestor.post("https://api.example.com/image")
    .body(Path.of("file.png"))
    .send();

Insecure SSL (Localhost/Self-Signed)

Ignore SSL certificate errors during development.

Requestor.get("https://localhost:8080")
    .insecure()
    .send();

Async Requests

Leverages CompletableFuture for non-blocking calls.

Requestor.get("https://slow-api.example.com")
    .sendAsync()
    .thenAccept(response -> {
        System.out.println("Got response: " + response.status());
    });

Handle Binary Data / Streams

// Get raw bytes
byte[] image = Requestor.get("https://example.com/photo").send().bytes();

// Stream response (efficient for large files)
try (InputStream stream = Requestor.get("https://example.com").send().stream()) {
    // Process stream...
}

Timeouts

Default timeout is 10 seconds. You can configure this per Requestor.

Requestor.get("https://api.example.com")
    .timeout(Duration.ofSeconds(30))
    .send();

API Reference

Method	Description
Requestor.get(url)	Starts a GET request builder.
Requestor.post(url)	Starts a POST request builder.
Requestor.put(url)	Starts a PUT request builder.
Requestor.delete(url)	Starts a DELETE request builder.
Requestor.patch(url)	Starts a PATCH request builder.
Requestor.fetchToken(...)	Helper for OAuth 2.0 Client Credentials flow.
.header(key, val)	Adds a single header.
.auth(user, pass)	Adds Basic Auth header.
.auth(token)	Adds Bearer Auth header.
.body(string/bytes/path)	Sets body content.
.timeout(duration)	Sets request timeout (Default: 10s).
.insecure()	Disables SSL certificate validation for this Requestor.
.send()	Executes sync, returns Response.
.sendAsync()	Executes async, returns CompletableFuture<Response>.

License

Apache-2.0 license