REST Catalog Configuration

Configuration endpoint for REST Catalog API discovery and setup

Configuration API

The configuration endpoint allows clients to discover server capabilities and receive catalog configuration.

Get Catalog Configuration

Retrieve catalog configuration settings from the server.

GET /v1/config

Query Parameters

warehouse · string

Warehouse location or identifier to request from the service.

Request Example

curl -X GET "https://catalog.example.com/v1/config?warehouse=prod" \
  -H "Authorization: Bearer <token>"

Response

defaults · object

Properties that should be used as default configuration. Applied before client configuration.

Show properties

[key] · string

Configuration property value

overrides · object

Properties that should be used to override client configuration. Applied after defaults and client configuration.

Show properties

[key] · string

Configuration property value

endpoints · array

List of endpoints supported by the server. Each endpoint is formatted as <HTTP verb> <resource path>.

If not provided, a default set of endpoints is assumed.

idempotency-key-lifetime · string (duration)

Client reuse window for an Idempotency-Key (ISO-8601 duration, e.g., PT30M, PT24H).

Indicates how long clients may reuse an idempotency key. Presence indicates server supports idempotency.

Response Example

{
  "overrides": {
    "warehouse": "s3://bucket/warehouse/"
  },
  "defaults": {
    "clients": "4"
  },
  "idempotency-key-lifetime": "PT30M",
  "endpoints": [
    "GET /v1/{prefix}/namespaces/{namespace}",
    "GET /v1/{prefix}/namespaces",
    "POST /v1/{prefix}/namespaces",
    "GET /v1/{prefix}/namespaces/{namespace}/tables/{table}",
    "GET /v1/{prefix}/namespaces/{namespace}/views/{view}"
  ]
}

Status Codes

• 200 OK - Configuration retrieved successfully
• 400 Bad Request - Invalid request parameters
• 401 Unauthorized - Authentication required
• 403 Forbidden - Not authorized to access configuration
• 419 Authentication Timeout - Authentication expired
• 503 Service Unavailable - Service temporarily unavailable

Configuration Properties

How Configuration is Applied

Catalog configuration is constructed in this order:

1. Defaults from server response
2. Client configuration provided by the application
3. Overrides from server response

This allows servers to:

• Suggest default values that clients can override
• Enforce specific values that cannot be changed by clients

Common Configuration Properties

Warehouse Location

The root location for table data:

{
  "overrides": {
    "warehouse": "s3://my-bucket/warehouse/"
  }
}

Client Pool Size

Number of HTTP client connections:

{
  "defaults": {
    "clients": "4"
  }
}

Namespace Separator

Character used to separate namespace levels (default: 0x1F):

{
  "overrides": {
    "namespace-separator": "."
  }
}

OAuth2 Configuration

OAuth2 server URI for authentication:

{
  "overrides": {
    "oauth2-server-uri": "https://auth.example.com/oauth/token"
  }
}

Additional Catalog Properties

Servers may return any Iceberg catalog configuration property:

• io-impl - FileIO implementation class
• lock-impl - Lock implementation class
• cache-enabled - Enable metadata caching
• cache.expiration-interval-ms - Cache expiration time

See Catalog Properties for a full list.

Endpoint Discovery

The endpoints array advertises which API operations the server supports.

Default Endpoints

If endpoints is not provided, clients should assume support for:

• GET /v1/{prefix}/namespaces
• POST /v1/{prefix}/namespaces
• GET /v1/{prefix}/namespaces/{namespace}
• DELETE /v1/{prefix}/namespaces/{namespace}
• POST /v1/{prefix}/namespaces/{namespace}/properties
• GET /v1/{prefix}/namespaces/{namespace}/tables
• POST /v1/{prefix}/namespaces/{namespace}/tables
• GET /v1/{prefix}/namespaces/{namespace}/tables/{table}
• POST /v1/{prefix}/namespaces/{namespace}/tables/{table}
• DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table}
• POST /v1/{prefix}/namespaces/{namespace}/register
• POST /v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics
• POST /v1/{prefix}/tables/rename
• POST /v1/{prefix}/transactions/commit

Checking Endpoint Support

Before calling an endpoint, check if it’s in the advertised list:

boolean supportsViews = config.endpoints().contains(
  "GET /v1/{prefix}/namespaces/{namespace}/views/{view}"
);

if (supportsViews) {
  // Safe to call view endpoints
}

Idempotency Support

The idempotency-key-lifetime field indicates:

1. If present: Server supports idempotency keys
2. Value: How long clients can reuse the same key

Using Idempotency Keys

POST /v1/production/namespaces HTTP/1.1
Host: catalog.example.com
Authorization: Bearer <token>
Idempotency-Key: 017F22E2-79B0-7CC3-98C4-DC0C0C07398F
Content-Type: application/json

{
  "namespace": ["accounting", "tax"],
  "properties": {
    "owner": "finance-team"
  }
}

Key Requirements

• Format: UUIDv7 (RFC 9562)
• Must be globally unique
• Reuse same key when retrying the same operation
• Generate new key for different operations
• Don’t reuse after lifetime expires

Client Implementation

Initialization Flow

public class RestCatalog {
  public void initialize(String uri, Map<String, String> properties) {
    // 1. Call /config endpoint
    ConfigResponse config = client.get(uri + "/v1/config");
    
    // 2. Apply configuration in order
    Map<String, String> finalConfig = new HashMap<>();
    finalConfig.putAll(config.defaults());
    finalConfig.putAll(properties);
    finalConfig.putAll(config.overrides());
    
    // 3. Store supported endpoints
    this.supportedEndpoints = new HashSet<>(config.endpoints());
    
    // 4. Store idempotency support
    this.supportsIdempotency = config.idempotencyKeyLifetime() != null;
    this.idempotencyLifetime = Duration.parse(
      config.idempotencyKeyLifetime()
    );
  }
}

Configuration Caching

Cache configuration to avoid repeated calls:

private static final Duration CONFIG_CACHE_TTL = Duration.ofHours(1);

private ConfigResponse getCachedConfig() {
  if (cachedConfig == null || cacheExpired()) {
    cachedConfig = fetchConfig();
    cacheTime = Instant.now();
  }
  return cachedConfig;
}

Use Cases

Multi-Warehouse Setup

# Development warehouse
GET /v1/config?warehouse=dev

# Production warehouse  
GET /v1/config?warehouse=prod

Server returns different configurations:

{
  "overrides": {
    "warehouse": "s3://dev-bucket/warehouse/"
  }
}

Custom Client Configuration

Client can set custom properties, but server overrides take precedence:

Map<String, String> clientProps = Map.of(
  "warehouse", "s3://my-bucket/",  // Will be overridden
  "clients", "8"                    // Will be used (not in overrides)
);

// Final config:
// warehouse: s3://server-bucket/ (from override)
// clients: 8 (from client)

Best Practices

1. Call /config first: Always retrieve configuration before other operations
2. Respect overrides: Don’t try to override server-enforced settings
3. Cache configuration: Avoid repeated calls with appropriate TTL
4. Check endpoint support: Gracefully handle unsupported operations
5. Use warehouse parameter: For multi-tenant deployments
6. Handle configuration changes: Re-fetch if errors suggest configuration issues

Related

• Catalog Properties - Complete property reference
• OAuth2 Authentication - Authentication configuration
• REST API Overview - API overview