Hi Dmitri, Thanks for your thoughts. This makes sense to me. I can try to start outlining which v1 API requests/responses seem to be non-compliant with RFC9110 and make an issue for that, which can lead to a v2 API in the future contribution!
Best, Adnan Hemani > On Sep 24, 2025, at 6:49 AM, Dmitri Bourlatchkov <[email protected]> wrote: > > 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://www.google.com/url?q=https://polaris.apache.org/in-dev/unreleased/evolution/&source=gmail-imap&ust=1759326626000000&usg=AOvVaw2D4KfLhXxXZBOwHzDSZZzV > > Cheers, > Dmitri. > > On Wed, Sep 24, 2025 at 9:33 AM Dmitri Bourlatchkov <[email protected] > <mailto:[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://www.google.com/url?q=https://github.com/apache/polaris/pull/2616&source=gmail-imap&ust=1759326626000000&usg=AOvVaw25HoA9dYovdxn6259ZhAq5>, >>> 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://www.google.com/url?q=https://datatracker.ietf.org/doc/rfc9110/&source=gmail-imap&ust=1759326626000000&usg=AOvVaw0iLgTQsbDH0-YUAUgdw42c> >>> 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
