Hey folks, Thanks for the feedback on the proposal.
I believe it’s best to retain the current 204 response code for HEAD requests in the REST API. Existing client and server implementations that adhere to the spec expect only 204 responses. Introducing an additional 200 response code would create backward compatibility issues and require all existing clients to be updated. While the MDN Web Docs' page on HEAD requests <https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD> and S3’s HeadObject documentation <https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadObject.html> suggest using 200 responses for HEAD requests, it’s better to stick with 204 since that’s what most servers and clients already support. We can treat 200 responses as exceptions rather than the rule. Clients can optionally handle 200 responses as a workaround while servers transition to sending 204 responses to fully adhere to the spec. Thanks all for the discussion! Best, Kevin Liu On Wed, Dec 18, 2024 at 1:00 AM Xuanwo <xua...@apache.org> wrote: > Hi, > > From my initial understanding of HTTP semantics, the HEAD request should > be treated like a GET request without a response body. Therefore, returning > a 204 for a HEAD request does not align with the concept held by most > developers. I support the idea of allowing a 200 response instead. > > For example, AWS S3 HeadObject also returns a 200 status code when the > file exists. > > Ref: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD > > On Wed, Dec 18, 2024, at 16:36, Fokko Driesprong wrote: > > Hey Kevin, > > I also agree with Yufei. For PyIceberg we had a long list of issues around > the head request (#1363 > <https://github.com/apache/iceberg-python/issues/1363> gives a nice > overview) to check if the table is there (and that also has just been > added to Java <https://github.com/apache/iceberg/pull/10999>). Allowing > 200 to unblock users quickly, but implementations should adhere to the > spec, and we should be reluctant with this kind of fixes. > > Kind regards, > Fokko > > Op wo 18 dec 2024 om 07:56 schreef Eduard Tudenhöfner < > etudenhoef...@apache.org>: > > I agree with Yufei's observation. Changing the return code in the spec > from 204 to 200 will just cause additional downstream work that doesn't > seem worth it. Returning 204 makes the API also very explicit in telling > that the request succeeded but that there's no content in the response that > the client needs to care about. > > Eduard > > On Tue, Dec 17, 2024 at 10:20 PM Yufei Gu <flyrain...@gmail.com> wrote: > > The distinction between 200 and 204 is subtle enough that I'm comfortable > using them interchangeably in this context. My main concern is that, if we > make this change, all clients—except for PyIceberg—will need to be updated > to support both 200 and 204, since a server could return either status > code. It might not be worth it. > > Yufei > > > On Tue, Dec 17, 2024 at 12:52 PM Kevin Liu <kevinjq...@apache.org> wrote: > > Hey folks, > > I’d like to propose adding status code 200 as a valid response for HEAD > requests in the Catalog REST API. Currently, the following HEAD requests > return status code 204 for a successful response: > * namespaceExists > <https://github.com/apache/iceberg/blob/540d6a6251e31b232fe6ed2413680621454d107a/open-api/rest-catalog-open-api.yaml#L372-L402> > * tableExists > <https://github.com/apache/iceberg/blob/540d6a6251e31b232fe6ed2413680621454d107a/open-api/rest-catalog-open-api.yaml#L1129-L1160> > * viewExists > <https://github.com/apache/iceberg/blob/540d6a6251e31b232fe6ed2413680621454d107a/open-api/rest-catalog-open-api.yaml#L1691-L1712> > > In PyIceberg, support for status code 200 has already been implemented for > table_exists > <https://github.com/apache/iceberg-python/pull/1389/files#diff-3bda7391ebd8aa3dcfd6703d8d2764830b9d9c35fa854188a37d69611274bd3dR890> > and namespace_exists > <https://github.com/apache/iceberg-python/pull/1434/files#diff-3bda7391ebd8aa3dcfd6703d8d2764830b9d9c35fa854188a37d69611274bd3dR882>. > The motivation for this change is to enable more intuitive and > user-friendly integrations with catalogs, as Fokko highlighted here > <https://github.com/apache/iceberg-python/issues/1363#issuecomment-2497462825>. > Standardizing this behavior in the Catalog REST spec would promote > consistency across implementations and make interactions easier for users > and client developers. > Would love to hear your thoughts on this proposal! > Best, > Kevin Liu > > Xuanwo > > https://xuanwo.io/ > >
