Agree - changes to the status codes should accompany a major version bump. Maybe log this as an issue and add to a 2.0.0 milestone release?
On Thu, Sep 18, 2025 at 4:08 PM Adnan Hemani <[email protected]> wrote: > Hi Dmitri, > > The change of the response code from 201 to 204 were discussed in Yufei’s > response within this email chain (and my response to his email as well). > > I can understand this being considered a “major change” requiring a major > version increment. In the interest of time, I can remove that change from > this PR to allow the rest of the changes and reintroduce the 201 -> 204 > change for the future. I, personally, do not think we are ready for 2.x.x - > and a change this small probably does not warrant a major version change on > its own. We can push merging that change off until later. > > Thanks for your thoughts! > > Best, > Adnan Hemani > > > On Sep 18, 2025, at 8:48 AM, Dmitri Bourlatchkov <[email protected]> > wrote: > > > > 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://www.google.com/url?q=https://polaris.apache.org/releases/1.0.1/evolution/%23semantic-versioning&source=gmail-imap&ust=1758815363000000&usg=AOvVaw0aeWhO8zol5dAFT5wCIkkG > > [2603] > https://www.google.com/url?q=https://github.com/apache/polaris/pull/2603&source=gmail-imap&ust=1758815363000000&usg=AOvVaw0vegLULgscdViZ8InwqP8O > > > > 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://www.google.com/url?q=https://datatracker.ietf.org/doc/html/rfc9110%23name-201-created&source=gmail-imap&ust=1758815363000000&usg=AOvVaw03kPSriTbQOeFYacs1yhiG> > 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 > >> > >> > >
