+1 for the proposal. In terms of the format, the current solution is simple
enough. But I propose to use a trimmed openAPI's format directly. It won't
add much cost as we can just take the minimum fields we want. But it opens
a window to extend it in the future. For example, it is easier if we want
to include operationID, or adding feature flags, or adding parameters. Here
is an example:
{
"resources": [
{
"/v1/{prefix}/namespaces":
{
"GET": {
"description": "List all namespaces"
}
},
{
"POST": {
"description": "Create a new namespace"
}
}
},
{
"path2": {}
}
...
]
}
Yufei
On Thu, Aug 15, 2024 at 8:47 AM Russell Spitzer <[email protected]>
wrote:
> I'm on board for this proposal. I was in the off-mail chats and I think
> this is probably our simplest approach going forward.
>
> On Thu, Aug 15, 2024 at 10:39 AM Dmitri Bourlatchkov
> <[email protected]> wrote:
>
>> OpenAPI tool will WARN a lot if Operation IDs overlap. Generated
>> code/html may also look odd in case of overlaps.
>>
>> All-in-all, I think the best practice is to define unique Operation IDs
>> up front.
>>
>> For Iceberg REST API, the yaml file is the API definition, so it should
>> not be a problem to ensure that Operation IDs are unique, I guess.
>>
>> Cheers,
>> Dmitri.
>>
>> On Thu, Aug 15, 2024 at 11:32 AM Eduard Tudenhöfner <
>> [email protected]> wrote:
>>
>>> Hey Jack,
>>>
>>> thanks for the feedback. I replied in the doc but I can reiterate my
>>> answer here too: The *path* is unique and required so that feels more
>>> appropriate than requiring to have an optional *operationId* in the
>>> OpenAPI spec.
>>> Additionally, using the path is more straight-forward when we introduce
>>> v2 endpoints, while you would have to make sure that all *operationIds*
>>> are unique across endpoints (and I'm not sure if OpenAPI tools actually
>>> enforce uniqueness).
>>>
>>>
>>>
>>> On Thu, Aug 15, 2024 at 5:20 PM Jack Ye <[email protected]> wrote:
>>>
>>>> Hi Eduard,
>>>>
>>>> In general I agree with this proposal, thanks for putting this up! Just
>>>> one question (which I also added in the design), what are the thoughts
>>>> behind using "<HTTP VERB> <resource path from REST spec>", vs using the
>>>> operationId defined in the OpenAPI?
>>>>
>>>> The operationId approach definitely looks much cleaner to me, but (1)
>>>> in OpenAPI it is not a requirement to define it, and (2) right now there
>>>> are some inconsistent operationIds, for example UpdateTable is the
>>>> operationId, but CommitTable is used for all request and response models.
>>>> But these are all pretty solvable issues because we can enforce operationId
>>>> to be required in the Iceberg spec, and fix it to be consistent, assuming
>>>> nobody is taking a dependency on these operationIds right now.
>>>>
>>>> Personally speaking, I am pretty neutral on this topic, but curious
>>>> what everyone thinks.
>>>>
>>>> Best,
>>>> Jack Ye
>>>>
>>>>
>>>>
>>>> On Wed, Aug 14, 2024 at 9:20 AM Eduard Tudenhöfner <
>>>> [email protected]> wrote:
>>>>
>>>>> Hey Dmitri,
>>>>>
>>>>> this proposal is the result of the community feedback from the
>>>>> Capabilities proposal. Ultimately the capabilities turned out to entail
>>>>> more complexity than necessary and so this proposal solves the core
>>>>> problem
>>>>> while keeping complexity and spec changes to an absolute minimum.
>>>>>
>>>>> Eduard
>>>>>
>>>>> On Wed, Aug 14, 2024 at 5:15 PM Dmitri Bourlatchkov
>>>>> <[email protected]> wrote:
>>>>>
>>>>>> Hi Eduard,
>>>>>>
>>>>>> How is this proposal related to the Server Capabilities discussion?
>>>>>>
>>>>>> Thanks,
>>>>>> Dmitri.
>>>>>>
>>>>>> On Wed, Aug 14, 2024 at 5:14 AM Eduard Tudenhöfner <
>>>>>> [email protected]> wrote:
>>>>>>
>>>>>>> Hey everyone,
>>>>>>>
>>>>>>> I'd like to propose a way for REST servers to communicate to clients
>>>>>>> what endpoints it supports via a new *endpoints* field in the
>>>>>>> *CatalogConfig* of the *v1/config* endpoint.
>>>>>>>
>>>>>>> This enables clients to make better decisions and clearly signal
>>>>>>> that a particular endpoint isn’t supported.
>>>>>>>
>>>>>>> I opened #10937 <https://github.com/apache/iceberg/issues/10937> to
>>>>>>> track the proposal in GH. Please find the proposal doc here
>>>>>>> <https://docs.google.com/document/d/1krcIaLfxtBFDABU5ssLmf64zyHgE8BRncpGPIMTWlxo/edit?usp=sharing>
>>>>>>> (estimated
>>>>>>> read time: 5 minutes). The proposal requires a Spec change, which can be
>>>>>>> seen in #10928 <https://github.com/apache/iceberg/pull/10928>.
>>>>>>>
>>>>>>>
>>>>>>> Thanks,
>>>>>>>
>>>>>>> Eduard
>>>>>>>
>>>>>>
