REST Endpoint Discovery

[nastra]

Motivation

The Iceberg OpenAPI REST specification defines a set of endpoints with their request and response definitions and describes how these endpoints need to be implemented by Iceberg REST clients and servers.

Adding new functionality to the REST specification often entails the addition of new endpoints. However, Iceberg REST clients currently don’t have any knowledge about whether such new endpoints are supported by a REST server implementing the Iceberg REST specification.

Such a scenario can result in ambiguous error responses on the REST client and require additional error handling (#9754, #9853) in order to not break functionality when using such new features with engines like Spark.

This proposal allows a server to communicate to clients what endpoints it supports via a new endpoints field in the CatalogConfig of the v1/config endpoint. This enables clients to make better decisions and clearly signal that a particular endpoint isn’t supported.

Goals

• Allow a server to communicate to clients what endpoints it supports
• Allow clients to avoid calling unsupported endpoints

Non-Goals

• OpenAPI REST Specification versioning

Proposal document

https://docs.google.com/document/d/1krcIaLfxtBFDABU5ssLmf64zyHgE8BRncpGPIMTWlxo/edit?usp=sharing

Additional PRs

#10928 / #10929

Specifications

• Table
• View
• REST
• Puffin
• Encryption
• Other

[nastra]

this is done