Re: breaking changes, just to recap our approach to evolving Polaris [1]: adding a v2 API is _not_ a breaking change (clients can choose which API version they target in their calls).
[1] https://polaris.apache.org/in-dev/unreleased/evolution/ Cheers, Dmitri. On Wed, Sep 24, 2025 at 9:33 AM Dmitri Bourlatchkov <[email protected]> wrote: > Hi Adnan, > > Thank you for starting this discussion. > > Your point about the status code for the revokeGrantFromCatalogRole is > valid, however, from my POV it is a very minor point considering the > structure of the Management API requests and responses in general. > > For example, the deletion of grants is framed as a POST > on /catalogs/{catalogName}/catalog-roles/{catalogRoleName}/grants while the > creation of grants is a PUT on the same path. In my opinion, this is not > quite aligned with REST/HTTP principles. > > If we want to bring this API closer to various related specs, I believe we > need to have a holistic look at it and probably produce version 2 of this > API as opposed to making incremental breaking changes to version 1 of this > API (as discussed before this response code change is pretty much a > breaking change). > > Cheers, > Dmitri. > > On Tue, Sep 23, 2025 at 7:53 PM Adnan Hemani > <[email protected]> wrote: > >> Hi all, >> >> This is a dedicated email thread for the proposal at #2616 < >> https://github.com/apache/polaris/pull/2616>, which I’ve proposed for a >> potential 2.0.0 release. >> >> The rationale for making this change is that returning a 201 (Created) >> response code is incorrect and technically, in violation of RFC 9110 < >> https://datatracker.ietf.org/doc/rfc9110/> Section 15.3.2, which reads: >> >> > The 201 (Created) status code indicates that the request has been >> > fulfilled and has resulted in one or more new resources being >> > created. >> >> Given there are no resources being created, according to spec, we should >> definitely not be returning back a 201 response code. In line with similar >> APIs currently in Polaris, I believe the correct response code would be 204 >> (No Content), as we only return successfully on this API if the processing >> of this revocation is complete - there is no additional information present >> in processing this call that was not already present in the request. >> >> As for consequences of making this change, I don’t see them being >> extremely large if done properly via a major version bump - which implies >> that there can be breaking changes as part of the release already. Changing >> clients from expecting HTTP code 201 to 204 should not be a cumbersome >> change comparatively to what other potentially breaking changes may be part >> of the release already. >> >> Best, >> Adnan Hemani > >
