Hi all, Thanks for the responses - and sorry for the delay, the past few weeks have been quite busy.
I agree with all the points presented. * I will start a vote soon for the following endpoints, once I have a draft PR that shows the proposed changes: createCatalog, createPrincipalRole, createCatalogRole. * For addGrantToCatalogRole/revokeGrantFromCatalogRole, I will use the information (GrantResource) from the incoming request. I do agree with Yufei on the point that perhaps revokeGrantFromCatalogRole should return 204 (No Content) rather than 201 (Created) - this is in line with other similar APIs (reference revokePrincipalRole and revokeCatalogRoleFromPrincipalRole). I will include this change in the previously-mentioned vote. Best, Adnan Hemani > On Sep 8, 2025, at 8:39 PM, Yufei Gu <flyrain...@gmail.com> wrote: > > 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 > <adnan.hem...@snowflake.com.invalid > <mailto:adnan.hem...@snowflake.com.invalid>> 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://www.google.com/url?q=https://datatracker.ietf.org/doc/html/rfc9110%23name-201-created&source=gmail-imap&ust=1757993986000000&usg=AOvVaw2lBZLiEw5_lovepJr-pP9l> >> 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
