REST Java Client

RESTApi is a Java client for the Paimon REST catalog. Use it to issue catalog metadata requests without bringing in the full table read/write bundle.

What you need	API or reference
List and manage catalog objects from Java	RESTApi, shown below
Load a Table and read or write rows	Java API with a REST catalog
Implement an HTTP client or catalog server	REST API specification
Administrative endpoints	Management API

Dependency

Maven dependency:

<dependency>
  <groupId>org.apache.paimon</groupId>
  <artifactId>paimon-api</artifactId>
  <version>2.2-SNAPSHOT</version>
</dependency>

Or download the jar file:

Paimon API.

Connect and list tables

Set the server URI, warehouse identifier, and authentication options. The warehouse value is interpreted by the server; it is not necessarily a filesystem path. The example uses the bearer token provider, whose configuration value is spelled bear.

import org.apache.paimon.options.Options;
import org.apache.paimon.rest.RESTApi;

import java.util.List;

import static org.apache.paimon.options.CatalogOptions.WAREHOUSE;
import static org.apache.paimon.rest.RESTCatalogOptions.DLF_ACCESS_KEY_ID;
import static org.apache.paimon.rest.RESTCatalogOptions.DLF_ACCESS_KEY_SECRET;
import static org.apache.paimon.rest.RESTCatalogOptions.TOKEN;
import static org.apache.paimon.rest.RESTCatalogOptions.TOKEN_PROVIDER;
import static org.apache.paimon.rest.RESTCatalogOptions.URI;

public class RESTApiExample {

    public static void main(String[] args) {
        Options options = new Options();
        options.set(URI, "<catalog server url>");
        options.set(WAREHOUSE, "my_instance_name");
        setBearerToken(options); // or setDlfToken

        RESTApi api = new RESTApi(options);
        List<String> tables = api.listTables("my_database");
        System.out.println(tables);
    }

    private static void setBearerToken(Options options) {
        options.set(TOKEN_PROVIDER, "bear");
        options.set(TOKEN, "<token>");
    }

    private static void setDlfToken(Options options) {
        options.set(TOKEN_PROVIDER, "dlf");
        options.set(DLF_ACCESS_KEY_ID, "<access-key-id>");
        options.set(DLF_ACCESS_KEY_SECRET, "<access-key-secret>");
    }
}

Entity labels

The experimental label methods use a single endpoint family for all server-supported entity types. Names are canonical, server-defined strings within the configured prefix. For a server that uses sales.orders to identify a table:

api.upsertLabel("TABLE", "sales.orders", "domain", "sales");
String domain = api.getLabel("TABLE", "sales.orders", "domain").getValue();
api.listLabels("TABLE", "sales.orders"); // Follows all pages.
api.listLabelsPaged("TABLE", "sales.orders", 100, null); // Reads one page.
api.deleteLabel("TABLE", "sales.orders", "domain");

When using RESTCatalog, call restCatalog.labelManagement() to obtain the same operations through LabelManagement, with Label objects as read results. This reuses the catalog's authentication and prefix configuration. See Java catalog access.

Upsert creates or replaces one binding using POST on the same single-key path used by GET and DELETE. Its request body contains only value. It requires the target entity to exist. Deleting an absent binding succeeds; deleting from a missing entity fails. Servers must implement these endpoints; the client does not fall back to table options or snapshot tags. See the label wire contract.

Authentication and table access

See bearer authentication or DLF authentication for provider configuration. Supply credentials through your application's configuration; the placeholders above illustrate the option names.

To use the full table API, add the Java bundle and create a catalog with metastore=rest, the server uri, warehouse, and the same authentication options. See REST catalog configuration for an example. Loading table metadata and reading its data files are separate operations, so configure storage access as required by the catalog.

Semantic view definitions

RESTApi exposes upsertSemanticView, getSemanticView, listSemanticViews, listSemanticViewsPaged, and deleteSemanticView. Upsert and get return GetSemanticViewResponse. Use RESTCatalog.semanticViewManagement() for the domain API backed by an existing catalog. See Semantic Views for Java examples, upsert behavior, server integration requirements, and the definition format.