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 < etudenhoef...@apache.org> 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 <yezhao...@gmail.com> 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 < >> etudenhoef...@apache.org> 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 >>> <dmitri.bourlatch...@dremio.com.invalid> 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 < >>>> etudenhoef...@apache.org> 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 >>>>> >>>>
