Implementation:Apache Paimon ResourcePaths

Knowledge Sources	Apache_Paimon
Domains	URL Construction, REST API Routing, Path Encoding
Last Updated	2026-02-08 00:00 GMT

Overview

ResourcePaths constructs URL paths for all REST catalog API endpoints, encoding database names, table names, and other identifiers into properly formatted resource paths.

Description

ResourcePaths is initialized with a catalog prefix (from RESTCatalogInternalOptions.PREFIX) that is URL-encoded. The class provides methods for each resource type that build paths using a slash joiner pattern. These include databases(), database(name), tables(db), table(db, name), partitions(db, table), branches(db, table), tags(db, table), views(db), functions(db), and many more including commit, rollback, register, token, snapshot, and auth endpoints.

All path components are URL-encoded via encodeString() to ensure proper handling of special characters in identifiers. The static config() method provides the configuration endpoint path. The class uses Guava's Joiner to concatenate path segments, skipping null values for optional components.

This class serves as the single source of truth for all REST API URL paths. By centralizing path construction, it ensures consistent URL formatting across all API operations and prevents encoding errors. Every RESTApi method uses ResourcePaths to build the correct endpoint URL, making this a critical routing component in the REST catalog implementation.

Usage

Use ResourcePaths internally within REST catalog implementations to construct consistent, properly encoded API endpoint URLs.

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-api/src/main/java/org/apache/paimon/rest/ResourcePaths.java
• Lines: 1-306

Signature

public class ResourcePaths {

    protected static final String V1 = "/v1";
    protected static final String DATABASES = "databases";
    protected static final String TABLES = "tables";
    protected static final String PARTITIONS = "partitions";
    protected static final String BRANCHES = "branches";
    protected static final String TAGS = "tags";
    protected static final String SNAPSHOTS = "snapshots";
    protected static final String VIEWS = "views";
    protected static final String FUNCTIONS = "functions";

    private final String prefix;

    public ResourcePaths(String prefix);

    public static String config();
    public static ResourcePaths forCatalogProperties(Options options);

    // Database paths
    public String databases();
    public String database(String databaseName);

    // Table paths
    public String tables();
    public String tables(String databaseName);
    public String table(String databaseName, String objectName);
    public String table(String tableId);
    public String tableDetails(String databaseName);
    public String renameTable();
    public String registerTable(String databaseName);

    // Snapshot paths
    public String tableSnapshot(String databaseName, String objectName);
    public String tableSnapshot(String databaseName, String objectName, String version);
    public String snapshots(String databaseName, String objectName);
    public String commitTable(String databaseName, String objectName);
    public String rollbackTable(String databaseName, String objectName);

    // Partition paths
    public String partitions(String databaseName, String objectName);
    public String markDonePartitions(String databaseName, String objectName);

    // Branch and tag paths
    public String branches(String databaseName, String objectName);
    public String branch(String databaseName, String objectName, String branchName);
    public String forwardBranch(String databaseName, String tableName, String branch);
    public String tags(String databaseName, String objectName);
    public String tag(String databaseName, String objectName, String tagName);

    // View paths
    public String views();
    public String views(String databaseName);
    public String view(String databaseName, String viewName);
    public String viewDetails(String databaseName);
    public String renameView();

    // Function paths
    public String functions();
    public String functions(String databaseName);
    public String function(String databaseName, String functionName);
    public String functionDetails(String databaseName);

    // Other paths
    public String authTable(String databaseName, String objectName);
    public String tableToken(String databaseName, String objectName);
}

Import

import org.apache.paimon.rest.ResourcePaths;

I/O Contract

Inputs

Name	Type	Required	Description
prefix	String	yes	Catalog prefix for URL paths
databaseName	String	no	Database name to encode in path
objectName	String	no	Table, view, or function name
branchName	String	no	Branch name for branch operations
tagName	String	no	Tag name for tag operations
version	String	no	Snapshot version identifier

Outputs

Name	Type	Description
path	String	URL-encoded resource path

Usage Examples

Creating ResourcePaths

import org.apache.paimon.rest.ResourcePaths;
import org.apache.paimon.options.Options;
import org.apache.paimon.rest.RESTCatalogInternalOptions;

// Create from options
Options options = new Options();
options.set(RESTCatalogInternalOptions.PREFIX, "my_catalog");
ResourcePaths paths = ResourcePaths.forCatalogProperties(options);

// Create directly
ResourcePaths paths2 = new ResourcePaths("my_catalog");

// Get config endpoint
String configPath = ResourcePaths.config();
System.out.println("Config: " + configPath);
// Output: /v1/config

Database Paths

import org.apache.paimon.rest.ResourcePaths;

ResourcePaths paths = new ResourcePaths("warehouse");

// List databases
String listPath = paths.databases();
System.out.println(listPath);
// Output: /v1/warehouse/databases

// Specific database
String dbPath = paths.database("my_database");
System.out.println(dbPath);
// Output: /v1/warehouse/databases/my_database

// Database with special characters
String encodedDbPath = paths.database("my-db@test");
System.out.println(encodedDbPath);
// Output: /v1/warehouse/databases/my-db%40test

Table Paths

import org.apache.paimon.rest.ResourcePaths;

ResourcePaths paths = new ResourcePaths("warehouse");

// List tables in database
String listTablesPath = paths.tables("my_db");
System.out.println(listTablesPath);
// Output: /v1/warehouse/databases/my_db/tables

// Specific table
String tablePath = paths.table("my_db", "my_table");
System.out.println(tablePath);
// Output: /v1/warehouse/databases/my_db/tables/my_table

// Get table by ID
String tableIdPath = paths.table("table-uuid-123");
System.out.println(tableIdPath);
// Output: /v1/warehouse/tables/id/table-uuid-123

// Table operations
String commitPath = paths.commitTable("my_db", "my_table");
System.out.println(commitPath);
// Output: /v1/warehouse/databases/my_db/tables/my_table/commit

String rollbackPath = paths.rollbackTable("my_db", "my_table");
System.out.println(rollbackPath);
// Output: /v1/warehouse/databases/my_db/tables/my_table/rollback

Snapshot Paths

import org.apache.paimon.rest.ResourcePaths;

ResourcePaths paths = new ResourcePaths("warehouse");

// Latest snapshot
String snapshotPath = paths.tableSnapshot("my_db", "my_table");
System.out.println(snapshotPath);
// Output: /v1/warehouse/databases/my_db/tables/my_table/snapshot

// Specific snapshot version
String versionPath = paths.tableSnapshot("my_db", "my_table", "5");
System.out.println(versionPath);
// Output: /v1/warehouse/databases/my_db/tables/my_table/snapshots/5

// List snapshots
String listPath = paths.snapshots("my_db", "my_table");
System.out.println(listPath);
// Output: /v1/warehouse/databases/my_db/tables/my_table/snapshots

Branch and Tag Paths

import org.apache.paimon.rest.ResourcePaths;

ResourcePaths paths = new ResourcePaths("warehouse");

// Branches
String branchesPath = paths.branches("my_db", "my_table");
System.out.println(branchesPath);
// Output: /v1/warehouse/databases/my_db/tables/my_table/branches

String branchPath = paths.branch("my_db", "my_table", "feature-branch");
System.out.println(branchPath);
// Output: /v1/warehouse/databases/my_db/tables/my_table/branches/feature-branch

String forwardPath = paths.forwardBranch("my_db", "my_table", "feature-branch");
System.out.println(forwardPath);
// Output: /v1/warehouse/databases/my_db/tables/my_table/branches/feature-branch/forward

// Tags
String tagsPath = paths.tags("my_db", "my_table");
System.out.println(tagsPath);
// Output: /v1/warehouse/databases/my_db/tables/my_table/tags

String tagPath = paths.tag("my_db", "my_table", "v1.0");
System.out.println(tagPath);
// Output: /v1/warehouse/databases/my_db/tables/my_table/tags/v1.0

Function and View Paths

import org.apache.paimon.rest.ResourcePaths;

ResourcePaths paths = new ResourcePaths("warehouse");

// Functions
String functionsPath = paths.functions("my_db");
System.out.println(functionsPath);
// Output: /v1/warehouse/databases/my_db/functions

String functionPath = paths.function("my_db", "my_udf");
System.out.println(functionPath);
// Output: /v1/warehouse/databases/my_db/functions/my_udf

// Global functions list
String globalFuncsPath = paths.functions();
System.out.println(globalFuncsPath);
// Output: /v1/warehouse/functions

// Views
String viewsPath = paths.views("my_db");
System.out.println(viewsPath);
// Output: /v1/warehouse/databases/my_db/views

String viewPath = paths.view("my_db", "my_view");
System.out.println(viewPath);
// Output: /v1/warehouse/databases/my_db/views/my_view

String renameViewPath = paths.renameView();
System.out.println(renameViewPath);
// Output: /v1/warehouse/views/rename

Related Pages

• Principle:Apache_Paimon_REST_Catalog_Protocol