Implementation:Apache Paimon HttpClient

Knowledge Sources	Apache_Paimon
Domains	REST API, HTTP Client, Network Communication
Last Updated	2026-02-08 00:00 GMT

Overview

HttpClient is an Apache HTTP client implementation for the Paimon REST catalog that handles GET, POST, and DELETE operations with authentication support.

Description

HttpClient implements the RESTClient interface to provide HTTP communication capabilities for Apache Paimon's REST catalog operations. It wraps Apache HttpClient 5 functionality and provides a simplified interface for making HTTP requests with proper error handling, authentication, and JSON serialization/deserialization.

The client automatically normalizes URIs by ensuring they have the correct HTTP/HTTPS protocol prefix and removing trailing slashes. It supports both simple and parameterized GET requests, POST requests with request bodies, and DELETE requests with optional bodies. All requests can include custom authentication headers through the RESTAuthFunction parameter.

Error handling is comprehensive: the client extracts error responses from failed requests, attempts to parse them as structured ErrorResponse objects, and delegates to a configurable ErrorHandler for processing. It also extracts request IDs from response headers for tracing and debugging purposes. The client uses a shared default HTTP client instance for efficiency and supports query parameter handling for GET requests.

Usage

Use HttpClient when implementing REST catalog operations in Apache Paimon that require HTTP communication with a catalog server. It's the primary HTTP client for catalog metadata operations, table management, and other REST API interactions with authentication support.

Code Reference

Source Location

Repository: Apache_Paimon
File: paimon-api/src/main/java/org/apache/paimon/rest/HttpClient.java

Signature

public class HttpClient implements RESTClient {
    private final String uri;
    private ErrorHandler errorHandler;

    public HttpClient(String uri);

    @Override
    public <T extends RESTResponse> T get(
            String path, Class<T> responseType, RESTAuthFunction restAuthFunction);

    @Override
    public <T extends RESTResponse> T get(
            String path,
            Map<String, String> queryParams,
            Class<T> responseType,
            RESTAuthFunction restAuthFunction);

    @Override
    public <T extends RESTResponse> T post(
            String path, RESTRequest body, RESTAuthFunction restAuthFunction);

    @Override
    public <T extends RESTResponse> T post(
            String path,
            RESTRequest body,
            Class<T> responseType,
            RESTAuthFunction restAuthFunction);

    @Override
    public <T extends RESTResponse> T delete(String path, RESTAuthFunction restAuthFunction);

    @Override
    public <T extends RESTResponse> T delete(
            String path, RESTRequest body, RESTAuthFunction restAuthFunction);
}

Import

import org.apache.paimon.rest.HttpClient;

I/O Contract

Inputs

Name	Type	Required	Description
uri	String	Yes	Base URI for the REST catalog server
path	String	Yes	Path component to append to base URI
queryParams	Map<String, String>	No	Query parameters for GET requests
body	RESTRequest	No	Request body for POST/DELETE operations
responseType	Class<T>	No	Expected response type class for deserialization
restAuthFunction	RESTAuthFunction	No	Function to generate authentication headers

Outputs

Name	Type	Description
get()	T extends RESTResponse	Returns deserialized response from GET request
post()	T extends RESTResponse	Returns deserialized response from POST request (may be null)
delete()	T extends RESTResponse	Returns null (DELETE responses are not deserialized)
uri()	String	Returns the normalized base URI

Usage Examples

import org.apache.paimon.rest.HttpClient;
import org.apache.paimon.rest.RESTRequest;
import org.apache.paimon.rest.RESTResponse;
import org.apache.paimon.rest.auth.RESTAuthFunction;

// Create HTTP client for REST catalog
HttpClient client = new HttpClient("https://catalog.example.com/api");

// Example 1: Simple GET request
class ConfigResponse extends RESTResponse {
    private String version;
    public String getVersion() { return version; }
}

ConfigResponse config = client.get(
    "/v1/config",
    ConfigResponse.class,
    null  // no authentication
);
System.out.println("Catalog version: " + config.getVersion());

// Example 2: GET with query parameters
Map<String, String> params = new HashMap<>();
params.put("namespace", "default");
params.put("limit", "100");

TableListResponse tables = client.get(
    "/v1/tables",
    params,
    TableListResponse.class,
    authFunction
);

// Example 3: POST request with body
CreateTableRequest createRequest = new CreateTableRequest(
    "my_table",
    schema,
    partitionSpec
);

CreateTableResponse response = client.post(
    "/v1/tables",
    createRequest,
    CreateTableResponse.class,
    authFunction
);

// Example 4: POST without response body parsing
client.post(
    "/v1/tables/my_table/refresh",
    refreshRequest,
    authFunction  // responseType omitted, returns null
);

// Example 5: DELETE request
client.delete(
    "/v1/tables/my_table",
    authFunction
);

// Example 6: DELETE with body
DropTableRequest dropRequest = new DropTableRequest(true);
client.delete(
    "/v1/tables/my_table",
    dropRequest,
    authFunction
);

// Example 7: With authentication
RESTAuthFunction authFunction = (authParam) -> {
    Map<String, String> headers = new HashMap<>();
    headers.put("Authorization", "Bearer " + token);
    headers.put("Content-Type", "application/json");
    return headers;
};

TableResponse table = client.get(
    "/v1/tables/my_table",
    TableResponse.class,
    authFunction
);

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment