Implementation:Apache Paimon RestClient

Knowledge Sources	Apache_Paimon
Domains	HTTP Communication, Error Handling
Last Updated	2026-02-08 00:00 GMT

Overview

RestClient (HttpClient) implements the HTTP communication layer for the Paimon REST catalog, providing request execution, automatic retries with exponential backoff, and comprehensive error handling with typed exceptions.

Description

The `HttpClient` class extends the abstract `RESTClient` interface to provide GET, POST, and DELETE HTTP methods with authentication header injection. It uses the Python `requests` library with a configured session that implements exponential retry via `ExponentialRetry` (which wraps urllib3's `Retry` with backoff_factor=1, max_retries=3, and retry on 429, 502-504 status codes). Request URIs are normalized (ensuring http/https prefix and removing trailing slashes), and query parameters are URL-encoded. Authentication headers are generated per-request via a callback function that encapsulates the auth provider logic. Responses are automatically deserialized from JSON using the `JSON` utility class. Error handling is delegated to `DefaultErrorHandler` (implemented as a singleton), which maps HTTP status codes to specific typed exceptions: 400 → BadRequestException, 401 → NotAuthorizedException, 403 → ForbiddenException, 404 → NoSuchResourceException, 409 → AlreadyExistsException, 500 → ServiceFailureException, 501 → NotImplementedException, 503 → ServiceUnavailableException. Request duration is logged for observability using nanosecond-precision timestamps. The session timeout is set to 180 seconds for both connection and read.

This design provides a robust HTTP foundation with automatic retry logic and structured error handling, making the REST catalog resilient to transient network failures.

Usage

HttpClient is used internally by RESTApi to communicate with the Paimon REST catalog server. Applications typically don't interact with it directly.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-python/pypaimon/api/client.py

Signature

class HttpClient(RESTClient):
    REQUEST_ID_KEY = "x-request-id"
    DEFAULT_REQUEST_ID = "unknown"

    def __init__(self, uri: str): ...

    def get(self, path: str, response_type: Type[T],
            rest_auth_function: Callable[[RESTAuthParameter], Dict[str, str]]) -> T: ...

    def get_with_params(self, path: str, query_params: Dict[str, str],
                        response_type: Type[T],
                        rest_auth_function: Callable[[RESTAuthParameter], Dict[str, str]]) -> T: ...

    def post(self, path: str, body: RESTRequest,
             rest_auth_function: Callable[[RESTAuthParameter], Dict[str, str]]) -> T: ...

    def delete(self, path: str,
               rest_auth_function: Callable[[RESTAuthParameter], Dict[str, str]]) -> T: ...

class DefaultErrorHandler(ErrorHandler):
    def accept(self, error: ErrorResponse, request_id: str) -> None: ...

Import

from pypaimon.api.client import HttpClient, DefaultErrorHandler

I/O Contract

Inputs

Name	Type	Required	Description
uri	str	yes	Base URI for the REST catalog (e.g., "http://localhost:8080")
path	str	yes	Request path (e.g., "/v1/databases")
query_params	Dict[str, str]	no	URL query parameters
body	RESTRequest	no	Request body for POST/DELETE
rest_auth_function	Callable	yes	Function to generate auth headers
response_type	Type[T]	yes	Expected response type for deserialization

Outputs

Name	Type	Description
Response object	T	Deserialized response matching response_type
Exceptions	RESTException subclasses	Typed exceptions for different error codes

Usage Examples

Basic GET Request

from pypaimon.api.client import HttpClient
from pypaimon.api.api_response import GetDatabaseResponse

# Create client
client = HttpClient("http://localhost:8080")

# Define auth function
def auth_fn(params):
    return {"Authorization": "Bearer token123"}

# Execute GET request
response = client.get(
    path="/v1/databases/default",
    response_type=GetDatabaseResponse,
    rest_auth_function=auth_fn
)

POST Request with Body

from pypaimon.api.api_request import CreateDatabaseRequest

# Create request body
request = CreateDatabaseRequest(
    name="test_db",
    properties={"owner": "admin"}
)

# Execute POST
client.post(
    path="/v1/databases",
    body=request,
    rest_auth_function=auth_fn
)

Error Handling

from pypaimon.api.rest_exception import NoSuchResourceException

try:
    response = client.get(
        path="/v1/databases/nonexistent",
        response_type=GetDatabaseResponse,
        rest_auth_function=auth_fn
    )
except NoSuchResourceException as e:
    print(f"Database not found: {e}")

Related Pages

• Principle:Apache_Paimon_REST_Catalog_Protocol