Implementation:Apache Paimon RestApi

Knowledge Sources	Apache_Paimon
Domains	Catalog Management, API Design
Last Updated	2026-02-08 00:00 GMT

Overview

RESTApi is the high-level REST API client that provides typed methods for all Paimon catalog operations, orchestrating HTTP communication, authentication, request serialization, and response deserialization.

Description

The `RESTApi` class initializes by configuring an `HttpClient`, creating an auth provider via `AuthProviderFactory`, extracting custom headers with the "header." prefix, and optionally fetching server configuration (which merges remote options into local configuration). It exposes a comprehensive set of catalog operations: `list_databases()`, `list_databases_paged()` with pagination support, `create_database()`, `get_database()`, `drop_database()`, `alter_database()` for database-level operations; and `list_tables()`, `list_tables_paged()`, `create_table()`, `get_table()`, `drop_table()`, `rename_table()`, `alter_table()`, `load_table_token()`, and `commit_snapshot()` for table-level operations. Paginated endpoints use `__list_data_from_page_api()` for automatic page iteration that follows `next_page_token` links until exhausted. Input validation is performed on all methods (checking for non-empty strings, non-null objects). Each method constructs the appropriate request object (CreateDatabaseRequest, AlterTableRequest, CommitTableRequest, etc.), calls the HTTP client with the correct resource path (generated by `ResourcePaths`) and response type, and returns typed response objects. The `rest_auth_function` is constructed during initialization and captures both base headers and the auth provider for injection into each request.

This facade pattern abstracts away all HTTP, serialization, auth, and pagination complexity, providing a clean typed interface that the catalog layer uses to interact with the REST server.

Usage

RESTApi is used internally by REST catalog implementations to perform metadata operations. It can also be used directly for custom integrations.

Code Reference

Source Location

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

Signature

class RESTApi:
    HEADER_PREFIX = "header."

    def __init__(self, options: Union[Options, Dict[str, str]],
                 config_required: bool = True): ...

    # Database operations
    def list_databases(self) -> List[str]: ...
    def list_databases_paged(self, max_results: Optional[int] = None,
                             page_token: Optional[str] = None,
                             database_name_pattern: Optional[str] = None) -> PagedList[str]: ...
    def create_database(self, name: str, properties: Dict[str, str]) -> None: ...
    def get_database(self, name: str) -> GetDatabaseResponse: ...
    def drop_database(self, name: str) -> None: ...
    def alter_database(self, name: str, removals: Optional[List[str]] = None,
                       updates: Optional[Dict[str, str]] = None): ...

    # Table operations
    def list_tables(self, database_name: str) -> List[str]: ...
    def create_table(self, identifier: Identifier, schema: Schema) -> None: ...
    def get_table(self, identifier: Identifier) -> GetTableResponse: ...
    def drop_table(self, identifier: Identifier) -> GetTableResponse: ...
    def rename_table(self, source_identifier: Identifier,
                     target_identifier: Identifier) -> None: ...
    def alter_table(self, identifier: Identifier, changes: List): ...
    def load_table_token(self, identifier: Identifier) -> GetTableTokenResponse: ...
    def commit_snapshot(self, identifier: Identifier, table_uuid: Optional[str],
                        snapshot: Snapshot,
                        statistics: List[PartitionStatistics]) -> bool: ...

Import

from pypaimon.api.rest_api import RESTApi
from pypaimon.common.options import Options

I/O Contract

Inputs

Name	Type	Required	Description
options	Options/Dict	yes	Configuration including URI, warehouse, auth settings
config_required	bool	no	Whether to fetch remote configuration (default: True)

Outputs

Name	Type	Description
Database list	List[str]	Database names
Table list	List[str]	Table names
Response objects	GetDatabaseResponse, GetTableResponse, etc.	Typed metadata responses

Usage Examples

Initialize REST API

from pypaimon.api.rest_api import RESTApi

# Initialize with options
options = {
    "uri": "http://localhost:8080",
    "warehouse": "my_warehouse",
    "auth.type": "basic",
    "auth.username": "admin",
    "auth.password": "secret"
}

api = RESTApi(options)

Database Operations

# List all databases
databases = api.list_databases()

# Create database
api.create_database("test_db", properties={"owner": "admin"})

# Get database details
db = api.get_database("test_db")
print(f"Created at: {db.created_at}")

# Drop database
api.drop_database("test_db")

Table Operations

from pypaimon.common.identifier import Identifier
from pypaimon.schema.schema import Schema
from pypaimon.schema.data_types import DataField, AtomicType

# Create table
identifier = Identifier.create("default", "users")
schema = Schema(
    fields=[
        DataField(0, "id", AtomicType("INT")),
        DataField(1, "name", AtomicType("STRING"))
    ],
    primary_keys=["id"]
)
api.create_table(identifier, schema)

# List tables
tables = api.list_tables("default")

# Get table
table = api.get_table(identifier)
print(f"Table path: {table.path}")

# Drop table
api.drop_table(identifier)

Pagination

# List databases with pagination
page1 = api.list_databases_paged(max_results=10)
print(f"Databases: {page1.data}")

if page1.next_page_token:
    page2 = api.list_databases_paged(
        max_results=10,
        page_token=page1.next_page_token
    )

Related Pages

• Principle:Apache_Paimon_REST_Catalog_Protocol