I've seen a couple of +1s on the spec PR: https://github.com/apache/iceberg/pull/15746
Shall we move this to a vote? On Sat, Mar 28, 2026 at 2:21 PM Kevin Liu <[email protected]> wrote: > We can use `IcebergErrorResponse` to differentiate between route doesnt > exists (404) and resource/warehouse doesnt exists (404). This is what the > spec PR describes, > https://github.com/apache/iceberg/pull/15746/files#diff-02549ca620d020dc9ead80088cc14e311e12a69651fa8d394cd41a4308debb2eR165-R173 > > For example, > `google.com/v1/config` <http://google.com/v1/config> doesnt exist, so > ``` > python3 -c "import urllib.request; urllib.request.urlopen(' > http://google.com/v1/config')" > ``` > returns `urllib.error.HTTPError: HTTP Error 404: Not Found` > > And I would expect an IRC endpoint to return `NoSuchWarehouseError` > instead, with `"type": "NoSuchWarehouseException"`. > > Best, > Kevin Liu > > On Sat, Mar 28, 2026 at 10:08 AM Steven Wu <[email protected]> wrote: > >> 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 >>>>>>>>> >>>>>>>>
