Thanks for the proposal, Adnan. Returning representations from the create endpoints makes sense to me and will reduce a follow-up GET in most clients.
For addGrantToCatalogRole, the grant itself is more a relationship between entities than entity itself. I understand it returns 201(Created) now, but 204(No content) also seems fine. "revokeGrantFromCatalogRole" doesn't create any entity or relationship. Returning 204(no content) seems more suitable. With that, I'd try to avoid adding a response body to both. Yufei On Fri, Sep 5, 2025 at 3:04 PM Adnan Hemani <[email protected]> wrote: > Hi all, > > While instrumenting event generation for all APIs, I found multiple public > APIs which I would like to request a change to in order to better support > event instrumentation as little-to-no cost to performance and/or bytes sent > in a response. > > createCatalog > > This API currently returns (on a successful call): > Status: 201 CREATED > Body: Empty > I’d like to propose for it to return the following: > Status: 201 CREATED (no change) > Body: Catalog POJO > > I don’t see this as extremely controversial - unless there is some > historical reason for not doing this. RFC 9110 < > https://datatracker.ietf.org/doc/html/rfc9110#name-201-created> also > recommends describing the resource created. > > createPrincipalRole > > This API currently returns (on a successful call): > Status: 201 CREATED > Body: Empty > I’d like to propose for it to return the following: > Status: 201 CREATED (no change) > Body: Principal Role POJO > > Same reasoning as above. > > createCatalogRole > > This API currently returns (on a successful call): > Status: 201 CREATED > Body: Empty > I’d like to propose for it to return the following: > Status: 201 CREATED (no change) > Body: Catalog Role POJO > > Same reasoning as above. > > addGrantToCatalogRole > > This API currently returns (on a successful call): > Status: 201 CREATED > Body: Empty > I’d like to propose for it to return the following: > Status: 201 CREATED (no change) > Body: A new POJO containing the following fields: > PolarisPrivilege POJO (this contains: securable PolarisEntityType, > securable PolarisEntitySubType (if applicable), and grantee > PolarisEntityType (if applicable)) > GrantResource POJO > > This is slightly more complicated, but I believe the proposed POJOs are > still attempting to describe the newly-added Grant that was applied to the > Catalog Role. > > revokeGrantFromCatalogRole > > This API currently returns (on a successful call): > Status: 201 CREATED > Body: Empty > I’d like to propose for it to return the following: > Status: 201 CREATED (no change) > Body: A new POJO containing the following fields: > PolarisPrivilege POJO (this contains: securable PolarisEntityType, > securable PolarisEntitySubType (if applicable), and grantee > PolarisEntityType (if applicable)) > GrantResource POJO > Cascade boolean - which states whether this revoke should cascade down. > > This is slightly more complicated, but I believe the proposed POJOs are > still attempting to describe the newly-revoked Grant that was removed from > the catalog role. > > Let us start discussion here first to flesh this out. If the thread does > not get any traction within a few days, then I will start a community vote > for making these changes. Thanks! > > Best, > Adnan Hemani > >
