Thanks JB and Dmitri!
Responses to JB's points:
1. +1, I'll stick with listAccessibleCatalogs
2. +1, updated wording to "includes exactly the catalogs for which the
caller is authorized to call `getConfig`..."
3. Yes, and per Dmitri's suggestions in the PR, updated to define in the
Polaris spec itself in accordance with other Polaris style rather than
importing from the Iceberg spec
4. Agreed, I was a little loose in my description, but the PR actually does
define a whole array of objects in the response like ({"catalogs":
[{"name": "..."}]}) so it'll be extensible for the other getConfig
properties or any other fields we might decide we want.
5. I think the default/natural way this would behave would automatically
have external/federated catalogs already show up in the list, which IMO
would be working as intended since the goal of federated catalogs is to
allow the caller not to worry about whether they're federated or not.
For Shares, the behavior is a bit different (but may be better stated in
the follow-up PRs that actually add the Share-dispatching SPIs for the
data-plane) - Shares would ideally long-term expose the trimmed version of
the verbatim polaris-catalog-service.yaml contents under the redirected
/api/shares instead of /api/catalog. So from the *consumer* standpoint, the
/api/shares constitues their own "meta-catalog" endpoint that behaves the
same as all the polaris-catalog-service endpoints, including this new
/api/shares/polaris/discovery/v1/catalogs path.
Re: Dmitri: Good catch on the path overlap; moved it to
/polaris/discovery/v1/catalogs as you suggested.
Cheers,
Dennis
On Wed, Oct 28, 2026 at 10:45 AM Dmitri Bourlatchkov <[email protected]>
wrote:
> 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
> >
>
