Overview

Let's use Apache Iceberg REST Catalog API as a full list of the APIs that needs to implement.

Note that we will not cover all APIs in the spec. For example, some operations need to rewrite data files, which should be done by query engines such as Apache Spark or Hive.

Namespace

• GET /namespaces List namespaces
• POST /namespaces Create a namespace
• GET /namespaces/{namespace} Load the metadata properties
• HEAD /namespaces/{namespace} Check if a namespace exists
• DELETE /namespaces/{namespace} Drop a namespace from the catalog. Namespace must be empty.
• POST /namespaces/{namespace}/properties Set or remove properties on a namespace

Table

• GET /namespaces/{namespace}/tables List all table identifiers underneath a given namespace
• POST /namespaces/{namespace}/tables Create a table in the given namespace
• GET /namespaces/{namespace}/tables/{table} Load a table from the catalog
• DELETE /namespaces/{namespace}/tables/{table} Drop a table from the catalog
• HEAD /namespaces/{namespace}/tables/{table} Check if a table exists
• GET /namespaces/{namespace}/tables/{table}/credentials Load vended credentials for a table from the catalog
• POST /tables/rename Rename a table from its current name to a new name

Table Scan

WON'T DO. Those are designed for query engines to optimize scan queries.

• POST /namespaces/{namespace}/tables/{table}/plan Submit a scan for planning
• GET /namespaces/{namespace}/tables/{table}/plan/{plan-id} Fetches the result of scan planning for a plan-id
• DELETE /namespaces/{namespace}/tables/{table}/plan/{plan-id} Cancels scan planning for a plan-id
• POST /namespaces/{namespace}/tables/{table}/tasks Fetches result tasks for a plan task

Table Write

WON'T DO. These are designed for query engines to write new data or changes.

• POST /namespaces/{namespace}/register Register a table in the given namespace using given metadata file location
• POST /namespaces/{namespace}/tables/{table}/metrics Send a metrics report to this endpoint to be processed by the backend
• POST /transactions/commit Commit updates to multiple tables in an atomic operation

Table Updates

POST /namespaces/{namespace}/tables/{table} Commit updates to a table

This API includes multiple actions:

• Metadata
  • AssignUUIDUpdate
  • UpgradeFormatVersionUpdate
  • SetLocationUpdate
  • SetPropertiesUpdate
  • RemovePropertiesUpdate
  • EnableRowLineageUpdate
• Schema WON'T DO.
  • AddSchemaUpdate
  • SetCurrentSchemaUpdate
  • RemoveSchemasUpdate
• Partition Spec WON'T DO.
  • AddPartitionSpecUpdate
  • SetDefaultSpecUpdate
  • RemovePartitionSpecsUpdate
• Sort Order WON'T DO.
  • AddSortOrderUpdate
  • SetDefaultSortOrderUpdate
• Snapshot & Refs
  • AddSnapshotUpdate WON'T DO.
  • SetSnapshotRefUpdate
  • RemoveSnapshotsUpdate
  • RemoveSnapshotRefUpdate
• Statistics WON'T DO.
  • SetStatisticsUpdate
  • RemoveStatisticsUpdate
  • SetPartitionStatisticsUpdate
  • RemovePartitionStatisticsUpdate
• View
  • AddViewVersionUpdate
  • SetCurrentViewVersionUpdate

View

• GET /namespaces/{namespace}/views List all view identifiers underneath a given namespace
• GET /namespaces/{namespace}/views/{view} Load a view from the catalog
• DELETE /namespaces/{namespace}/views/{view} Drop a view from the catalog
• HEAD /namespaces/{namespace}/views/{view} Check if a view exists
• POST /views/rename Rename a view from its current name to a new name

View Edit

WON'T DO. These are designed for query engines to CREATE VIEW

• POST /namespaces/{namespace}/views Create a view in the given namespace
• POST /namespaces/{namespace}/views/{view} Replace a view

Misc.

• GET /v1/config List all catalog configuration settings
• Authorizations (OAuth2)
• BearerAuth