You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@iceberg.apache.org by Oğuzhan Ünlü <ce...@gmail.com> on 2026/03/24 11:33:42 UTC
[DISCUSS][SPEC] Add 404 response for /v1/config endpoint
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
Re: [DISCUSS][SPEC] Add 404 response for /v1/config endpoint
Posted by Ryan Blue <rd...@gmail.com>.
A prefix is not allowed for the config endpoint, so I don't think you would
have this problem.
On Wed, Apr 1, 2026 at 7:17 PM roryqi <ro...@apache.org> wrote:
> Which catalog configuration should we return if we specified the
> prefix and warehouse at the same time?
>
> Yufei Gu <fl...@gmail.com> 于2026年4月2日周四 06:08写道：
> >
> > Yes, let's!
> > Yufei
> >
> >
> > On Wed, Apr 1, 2026 at 3:00 PM Kevin Liu <ke...@apache.org> wrote:
> >>
> >> 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 <ke...@apache.org>
> 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 <st...@gmail.com>
> 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 <rd...@gmail.com> 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 <fl...@gmail.com>
> 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 <st...@gmail.com>
> 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 <rd...@gmail.com>
> 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 <fl...@gmail.com>
> 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 <ke...@apache.org>
> 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ü <
> cengoguzhanunlu@gmail.com> 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
>
Re: [DISCUSS][SPEC] Add 404 response for /v1/config endpoint
Posted by roryqi <ro...@apache.org>.
Which catalog configuration should we return if we specified the
prefix and warehouse at the same time?
Yufei Gu <fl...@gmail.com> 于2026年4月2日周四 06:08写道：
>
> Yes, let's!
> Yufei
>
>
> On Wed, Apr 1, 2026 at 3:00 PM Kevin Liu <ke...@apache.org> wrote:
>>
>> 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 <ke...@apache.org> 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` 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 <st...@gmail.com> 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 <rd...@gmail.com> 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 <fl...@gmail.com> 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 <st...@gmail.com> 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 <rd...@gmail.com> 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 <fl...@gmail.com> 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 <ke...@apache.org> 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ü <ce...@gmail.com> 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
Re: [DISCUSS][SPEC] Add 404 response for /v1/config endpoint
Posted by Yufei Gu <fl...@gmail.com>.
Yes, let's!
Yufei
On Wed, Apr 1, 2026 at 3:00 PM Kevin Liu <ke...@apache.org> wrote:
> 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 <ke...@apache.org> 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 <st...@gmail.com> 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 <rd...@gmail.com> 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 <fl...@gmail.com> 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 <st...@gmail.com>
>>>>> 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 <rd...@gmail.com> 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 <fl...@gmail.com>
>>>>>>> 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 <ke...@apache.org>
>>>>>>>> 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ü <
>>>>>>>>> cengoguzhanunlu@gmail.com> 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
>>>>>>>>>>
>>>>>>>>>
Re: [DISCUSS][SPEC] Add 404 response for /v1/config endpoint
Posted by Kevin Liu <ke...@apache.org>.
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 <ke...@apache.org> 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 <st...@gmail.com> 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 <rd...@gmail.com> 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 <fl...@gmail.com> 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 <st...@gmail.com> 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 <rd...@gmail.com> 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 <fl...@gmail.com>
>>>>>> 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 <ke...@apache.org>
>>>>>>> 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ü <
>>>>>>>> cengoguzhanunlu@gmail.com> 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
>>>>>>>>>
>>>>>>>>
Re: [DISCUSS][SPEC] Add 404 response for /v1/config endpoint
Posted by Kevin Liu <ke...@apache.org>.
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 <st...@gmail.com> 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 <rd...@gmail.com> 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 <fl...@gmail.com> 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 <st...@gmail.com> 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 <rd...@gmail.com> 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 <fl...@gmail.com> 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 <ke...@apache.org>
>>>>>> 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ü <
>>>>>>> cengoguzhanunlu@gmail.com> 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
>>>>>>>>
>>>>>>>
Re: [DISCUSS][SPEC] Add 404 response for /v1/config endpoint
Posted by Steven Wu <st...@gmail.com>.
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 <rd...@gmail.com> 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 <fl...@gmail.com> 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 <st...@gmail.com> 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 <rd...@gmail.com> 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 <fl...@gmail.com> 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 <ke...@apache.org>
>>>>> 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ü <
>>>>>> cengoguzhanunlu@gmail.com> 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
>>>>>>>
>>>>>>
Re: [DISCUSS][SPEC] Add 404 response for /v1/config endpoint
Posted by Ryan Blue <rd...@gmail.com>.
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 <fl...@gmail.com> 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 <st...@gmail.com> 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 <rd...@gmail.com> 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 <fl...@gmail.com> 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 <ke...@apache.org>
>>>> 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ü <
>>>>> cengoguzhanunlu@gmail.com> 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
>>>>>>
>>>>>
Re: [DISCUSS][SPEC] Add 404 response for /v1/config endpoint
Posted by Yufei Gu <fl...@gmail.com>.
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 <st...@gmail.com> 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 <rd...@gmail.com> 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 <fl...@gmail.com> 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 <ke...@apache.org> 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ü <ce...@gmail.com>
>>>> 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
>>>>>
>>>>
Re: [DISCUSS][SPEC] Add 404 response for /v1/config endpoint
Posted by Steven Wu <st...@gmail.com>.
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 <rd...@gmail.com> 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 <fl...@gmail.com> 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 <ke...@apache.org> 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ü <ce...@gmail.com>
>>> 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
>>>>
>>>
Re: [DISCUSS][SPEC] Add 404 response for /v1/config endpoint
Posted by Ryan Blue <rd...@gmail.com>.
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 <fl...@gmail.com> 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 <ke...@apache.org> 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ü <ce...@gmail.com>
>> 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
>>>
>>
Re: [DISCUSS][SPEC] Add 404 response for /v1/config endpoint
Posted by Yufei Gu <fl...@gmail.com>.
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 <ke...@apache.org> 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ü <ce...@gmail.com>
> 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
>>
>
Re: [DISCUSS][SPEC] Add 404 response for /v1/config endpoint
Posted by Kevin Liu <ke...@apache.org>.
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ü <ce...@gmail.com>
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
>