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
