Hi Dennis, A separate discovery endpoint for non-management use cases makes sense from my POV.
I think we need to be careful about endpoint path overlaps, though. I left a few technical comments on [5891], but it looks fine to me in general. [5891] https://github.com/apache/polaris/pull/5891 Cheers, Dmitri. On Wed, Oct 28, 2026 at 1:19 AM Dennis Huo <[email protected]> wrote: > Hi All, > > I'd like to propose a small extension under the polaris-catalog-service > APIs: a way for a *data-plane* client to list the catalogs it can access. > > This relates to https://github.com/apache/polaris/issues/4573 as well as > an > emerging missing piece for the in-progress Polaris Shares API work. > > The basic problem is that today you already need to have the catalog name > to configure an Iceberg REST Client. Even though IRC's /config endpoint is > multi-catalog by nature, there's no analogous /catalogs endpoint yet in > IRC. > > Polaris' current listCatalogs operation is semantically a *management* > API's list, requiring a root-level CATALOG_LIST privilege and returning the > full Catalog API model json in the responses, including the > StorageConfiguration, for example. > > The proposal is to add GET /api/catalog/polaris/v1/catalogs, intended for a > data-plane reader that doesn't necessarily have any management-level > permissions, but has been granted a CatalogRole to "use" some catalogs. As > a starting point, we'd only return the *name* of the catalog that needs to > be passed to the "warehouse" field under the /config endpoint. > > This work *complements* the pruned management listCatalogs work related to > https://github.com/apache/polaris/pull/4831 rather than replacing it. The > key here is that despite being superficially similar to the admin-level > listCatalogs, the two serve different personas: > > - Data-plane discovery (this proposal): > - Batch form of: getConfig > - Entries hold: name only (but may add properties normally returned by > getConfig in the future) > - Pruned by: the caller's getConfig access-check / assignment of a > CatalogRole > - For: engines, tools, user-facing UIs and platforms that mount remote > catalogs > - Pruned management listCatalogs: > - Batch form of getCatalog > - Entries hold: full Catalog API model > - Pruned by: CATALOG_READ_PROPERTIES > - For: administrative tools/consoles > > This also keeps a cleaner split of data-plane personas accessing the > /api/catalog/ URL path, and only admin personas accessing the > /api/management/ URL path. > > I've opened a draft PR for this spec extension here: > https://github.com/apache/polaris/pull/5891 > > The specific operation-name of the new operation is up for discussion - I'm > proposing "listAccessibleCatalogs" as my preference. Others could be > listVisibleCatalogs, listAvailableCatalogs, listConnectableCatalogs, etc. > > Would love to hear everyone's thoughts. > > Thanks! > Dennis >
