Hi Adnan, Changes to response bodies LGTM.
However, PR [2603] that references this discussion thread, also changes one of the response codes from 201 to 204 (which was not yet discussed in this thread, if I'm not mistaken). The response code change appears to be meaningful, however, I believe it would be a breaking API change per our "evolution" policy [1] and as such will require a major version bump. My rationale for why this change is a "breaking" change is that the API spec declares a specific response code for all successful responses (it does not say that any 2xx is a success). Existing clients may rely on receiving 201 specifically, so when they start receiving 204 it could be unexpected. This is similar to renaming a request/response field or parameter. I'm personally ok with bumping the version to 2.0.0, but let's review the response code change a bit more before committing. I wonder what other community members think. [1] https://polaris.apache.org/releases/1.0.1/evolution/#semantic-versioning [2603] https://github.com/apache/polaris/pull/2603 Thanks, Dmitri. On Fri, Sep 5, 2025 at 6: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 > >
