Chatted with Yufei offline. The `warehouse/catalog` is a hidden concept in
the REST spec. If we could redo it, including it in the path (instead of as
a query parameter) might make more sense. E.g., The endpoint could look
like "/v1/{prefix}/config," where a 404 status would be perfect.Since it is too late to change that, I agree 404 is fine here. On Fri, Mar 27, 2026 at 10:00 AM Ryan Blue <[email protected]> wrote: > I think the difference between those examples and the config route is that > those examples identify resources that do not exist (namespace in both > cases). We also have cases where you could get a 404 indicating a namespace > or a table does not exist, but that indicates that the resource you're > looking for either does not exist (table) or can't exist (namespace > preventing table from being present). > > The config endpoint always exists, which is why this is odd. I think you > could argue that this is okay because it isn't really a resource that has > create/update/delete operations. I just don't know what the "correct" way > to handle this is in REST APIs. But then I've never been one that's too > strict about REST principles. > > On Thu, Mar 26, 2026 at 3:44 PM Yufei Gu <[email protected]> wrote: > >> I'd be cautious about 204 since it indicates a successful response. 404 >> seems fine to me. IRC spec uses it in multiple places, like [1] and [2] to >> indicate that certain entities do not exist. >> >> 1. >> https://github.com/apache/iceberg/blob/9534c9b3adc29d127ecc541ce131f49fd72f1980/open-api/rest-catalog-open-api.yaml#L539 >> 2. >> https://github.com/apache/iceberg/blob/9534c9b3adc29d127ecc541ce131f49fd72f1980/open-api/rest-catalog-open-api.yaml#L490 >> >> Yufei >> >> >> On Thu, Mar 26, 2026 at 2:03 PM Steven Wu <[email protected]> wrote: >> >>> >>> 404 may not be the best fit, as it generally indicates that the endpoint >>> itself could not be found. The endpoint receiving the query parameters >>> exists, and a lack of results is a valid outcome of the search/filter >>> operation, not a client error in forming the request URI. >>> >>> Maybe return 204 No Content as the request itself was valid and >>> successfully processed. >>> >>> On Thu, Mar 26, 2026 at 1:48 PM Ryan Blue <[email protected]> wrote: >>> >>>> This seems reasonable to me. I don't know if 404 is the right response >>>> since the endpoint always exists, but it's fine with me. >>>> >>>> On Wed, Mar 25, 2026 at 6:04 PM Yufei Gu <[email protected]> wrote: >>>> >>>>> It seems reasonable to add the 404 response. I noticed that the >>>>> warehouse parameter is optional. I assume this is meant for catalog >>>>> implementations that support exactly one catalog or warehouse here so that >>>>> client is OK to skip it, though please correct me if I am mistaken. In >>>>> that >>>>> case, a 404 would still make sense when that single warehouse is not yet >>>>> ready. >>>>> >>>>> parameters: >>>>> - name: warehouse >>>>> in: query >>>>> required: false >>>>> >>>>> >>>>> Yufei >>>>> >>>>> >>>>> On Tue, Mar 24, 2026 at 8:33 AM Kevin Liu <[email protected]> >>>>> wrote: >>>>> >>>>>> Thanks for raising this proposal! I think it makes sense to add this >>>>>> to the spec and be explicit about the error case. I found the place where >>>>>> Apache Polaris throws `NotFoundException` for the `/v1/config` endpoint. >>>>>> The specific error `type` field can be used to disambiguate a route 404 >>>>>> (URL doesn't exist) from a resource 404 (URL is valid, but the server >>>>>> cannot find the warehouse). >>>>>> >>>>>> Best, >>>>>> Kevin Liu >>>>>> >>>>>> [1] >>>>>> https://github.com/apache/polaris/blob/67daa9bb479eaa0ee6c4428984e253afc01b6efd/runtime/service/src/main/java/org/apache/polaris/service/catalog/iceberg/IcebergCatalogHandler.java#L1360 >>>>>> >>>>>> On Tue, Mar 24, 2026 at 4:34 AM Oğuzhan Ünlü < >>>>>> [email protected]> wrote: >>>>>> >>>>>>> Hi everyone, >>>>>>> >>>>>>> I'd like to propose a small addition to the REST catalog spec: >>>>>>> documenting HTTP 404 as a valid response for the /v1/config endpoint >>>>>>> when a >>>>>>> requested warehouse does not exist. >>>>>>> >>>>>>> The Rationale >>>>>>> >>>>>>> The /v1/config endpoint allows an optional query parameter for a >>>>>>> warehouse identifier, e.g. /v1/config?warehouse=mywarehouse. But the >>>>>>> openapi spec does not specify what should happen if the requested >>>>>>> warehouse >>>>>>> does not exist. >>>>>>> >>>>>>> Snowflake Open Catalog already returns a 404 for non-existent >>>>>>> warehouses: >>>>>>> >>>>>>> ``` >>>>>>> { >>>>>>> "error": { >>>>>>> "message": "Unable to find warehouse >>>>>>> NONEXISTENT_WAREHOUSE_12345", >>>>>>> "type": "NotFoundException", >>>>>>> "code": 404 >>>>>>> } >>>>>>> } >>>>>>> ``` >>>>>>> >>>>>>> This proposal therefore formalizes what Snowflake Open Catalog is >>>>>>> already doing in production. It seems sensible to formalize the 404 >>>>>>> response code, because this is consistent with other Iceberg REST >>>>>>> endpoints >>>>>>> which allow a 404 response code for missing resources (tables, >>>>>>> namespaces, >>>>>>> views). >>>>>>> >>>>>>> The Proposed Solution (PR-15746) >>>>>>> >>>>>>> Add a NoSuchWarehouseResponse to the OpenAPI spec for the /v1/config >>>>>>> endpoint, formalizing 404 as the response when a warehouse does not >>>>>>> exist. You can view the PR here: >>>>>>> https://github.com/apache/iceberg/pull/15746 . >>>>>>> >>>>>>> Looking forward to your thoughts. >>>>>>> >>>>>>> Best, >>>>>>> Oguzhan >>>>>>> >>>>>>
