​

REST Catalog API

​

Overview

• Catalog configuration and discovery
• Namespace operations (create, list, update, delete)
• Table operations (create, load, update, delete, rename)
• View operations (create, load, replace, delete, rename)
• Transaction support for multi-table commits
• Authentication and authorization patterns

​

API Version

​

Server URLs

{scheme}://{host}:{port}/{basePath}

https://catalog.example.com:443/v1

​

Authentication

• OAuth2 - Standard OAuth2 flows for token-based authentication
• Bearer Token - Direct bearer token authentication

Authorization: Bearer <token>

​

API Endpoints

​

Configuration

• GET /v1/config - Get catalog configuration and server capabilities

​

Namespaces

• GET /v1/{prefix}/namespaces - List namespaces
• POST /v1/{prefix}/namespaces - Create a namespace
• GET /v1/{prefix}/namespaces/{namespace} - Load namespace metadata
• HEAD /v1/{prefix}/namespaces/{namespace} - Check if namespace exists
• DELETE /v1/{prefix}/namespaces/{namespace} - Drop a namespace
• POST /v1/{prefix}/namespaces/{namespace}/properties - Update namespace properties

​

Tables

• GET /v1/{prefix}/namespaces/{namespace}/tables - List tables
• POST /v1/{prefix}/namespaces/{namespace}/tables - Create a table
• GET /v1/{prefix}/namespaces/{namespace}/tables/{table} - Load table metadata
• POST /v1/{prefix}/namespaces/{namespace}/tables/{table} - Update table
• DELETE /v1/{prefix}/namespaces/{namespace}/tables/{table} - Drop table
• HEAD /v1/{prefix}/namespaces/{namespace}/tables/{table} - Check if table exists
• POST /v1/{prefix}/tables/rename - Rename a table
• POST /v1/{prefix}/namespaces/{namespace}/register - Register existing table

​

Views

• GET /v1/{prefix}/namespaces/{namespace}/views - List views
• POST /v1/{prefix}/namespaces/{namespace}/views - Create a view
• GET /v1/{prefix}/namespaces/{namespace}/views/{view} - Load view metadata
• POST /v1/{prefix}/namespaces/{namespace}/views/{view} - Replace view
• DELETE /v1/{prefix}/namespaces/{namespace}/views/{view} - Drop view
• HEAD /v1/{prefix}/namespaces/{namespace}/views/{view} - Check if view exists
• POST /v1/{prefix}/views/rename - Rename a view

​

Transactions

• POST /v1/{prefix}/transactions/commit - Commit multi-table transaction

​

Common Patterns

​

Namespace Identifiers

accounting           → single-level namespace
accounting%1Ftax     → multi-level namespace (accounting.tax)

​

Pagination

• pageToken query parameter
• next-page-token in response

GET /v1/namespaces?pageToken=abc123&pageSize=100

​

Idempotency

Idempotency-Key: 017F22E2-79B0-7CC3-98C4-DC0C0C07398F

• Format: UUIDv7 (RFC 9562)
• Servers must return equivalent responses for repeated requests with the same key
• Key lifetime is advertised in catalog configuration

​

Prefix Parameter

/v1/production/namespaces
/v1/staging/namespaces

​

Response Codes

​

Success Codes

• 200 OK - Successful request with response body
• 201 Created - Resource created successfully
• 204 No Content - Successful request without response body
• 304 Not Modified - Resource unchanged (when using ETags)

​

Client Error Codes

• 400 Bad Request - Invalid request format or parameters
• 401 Unauthorized - Authentication required or failed
• 403 Forbidden - Authenticated but not authorized
• 404 Not Found - Resource does not exist
• 406 Not Acceptable - Operation not supported
• 409 Conflict - Resource already exists or commit conflict
• 419 Authentication Timeout - Authentication expired
• 422 Unprocessable Entity - Request semantically invalid

​

Server Error Codes

• 500 Internal Server Error - Server-side error
• 502 Bad Gateway - Gateway/proxy error
• 503 Service Unavailable - Temporary unavailability
• 504 Gateway Timeout - Gateway timeout

​

Error Response Format

{
  "error": {
    "message": "Namespace already exists: accounting.tax",
    "type": "NamespaceAlreadyExistsException",
    "code": 409,
    "stack": ["..."]
  }
}

​

Configuration Discovery

1. Discover server capabilities
2. Receive default and override configuration
3. Learn supported endpoints
4. Get idempotency key lifetime

GET /v1/config HTTP/1.1
Host: catalog.example.com
Authorization: Bearer <token>

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

​

Data Access Delegation

​

Vended Credentials

X-Iceberg-Access-Delegation: vended-credentials

​

Remote Signing

X-Iceberg-Access-Delegation: remote-signing

​

Best Practices

1. Always call /config first: Get server capabilities before making other requests
2. Use idempotency keys: Ensure safe retries for mutation operations
3. Handle pagination: Don’t assume all results fit in one response
4. Check supported endpoints: Not all servers implement all endpoints
5. Use appropriate timeouts: Respect server processing times
6. Cache configuration: Avoid repeated /config calls
7. Follow redirect responses: Handle 3xx responses appropriately

​

Specification Details

• Configuration - Catalog configuration and discovery
• Namespaces - Namespace management
• Tables - Table operations
• Views - View operations

​

OpenAPI Specification

source/open-api/rest-catalog-open-api.yaml

​

Reference Implementation

• Java REST catalog client
• Python REST catalog client
• Example server implementations

​

Related Resources

• Catalog Configuration - Catalog configuration properties
• Table Metadata - Table metadata format
• View Metadata - View metadata format
• OAuth2 Integration - Authentication setup