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 >> >>
