Hi all, I think we now need some PoCs. It would be good to see what a code-first approach would look like.
I also mentioned using different OpenAPI generators. I think I still have an old branch with the "jaxrs-spec" generator that I mentioned previously, I can open a PR for it if there is interest. Thanks, Alex On Wed, Mar 4, 2026 at 11:42 PM Dmitri Bourlatchkov <[email protected]> wrote: > > Hi Michael, > > I probably was not very clear in my earlier messages :) sorry about the > confusion. > > The way I see the OpenAPI tooling situation is that generating server-side > code from the YAML spec ensures that URI paths and payload types / > structures are compliant with the spec. > > On the other side of the coin, we have to manually write code to match the > generated stubs. (side note: this reminds my of CORBA :disappear: ) > > I find the latter part inconvenient from a human developer's perspective. > Also, if we have to adjust stubs to leverage something specific from the > platform (e.g. asynchronous processing), the (stub) code generation becomes > more of an obstacle than a help. > > Now, going back to specific proposals, I was thinking about leveraging > JaxRs annotations directly on hand-written endpoint implementation classes > (basically the methods binding to @Path annotations) and avoiding generated > server-side stubs. The code can still use generated classes for payload > serialization. I believe this will remove a good chunk of boiler-plate > code. > > WDYT? > > Cheers, > Dmitri. > > On Tue, Mar 3, 2026 at 8:32 PM Michael Collado <[email protected]> > wrote: > > > Sorry for the late reply. I guess I'm not sure what your proposal is. You > > are suggesting we go with the Java annotation-based approach and generate > > the OpenAPI yaml from the Java code, right? That's the code-first (or > > bottom-up) approach. > > > > I get the awkwardness of the spec-first approach, but IMO, it's less > > awkward than having to reconcile two specs after the fact, which is what > > we'd have to do in the bottom-up approach to ensure compliance with the > > Iceberg spec. Yes, we have to run the tests anyway to ensure behavior is > > correct, but runtime testing is both slower than compile-time checking and > > also, IME, doesn't drive the actual development process like interface > > changes do. E.g., optional parameters can simply be ignored during the > > integration tests, whereas they actually cause someone to make a conscious > > choice about handling them when the interface definition changes. One of > > the alternative tools that validates spec compliance seems like it > > would fill the gap, as Alex says, but TBH, I don't see the point. I guess I > > just don't feel as awkward with the spec-first approach. > > > > As I mentioned, I'm not tied to any particular tool for the code > > generation, so if there is an alternative that is less verbose or solve > > some particular problem better, I'd be open to hear it, but as for > > abandoning the code generation entirely, I feel there would need to be a > > strong technical reason to go that route more than just "general > > awkwardness". > > > > Mike > > > > On Tue, Feb 17, 2026 at 11:11 AM Dmitri Bourlatchkov <[email protected]> > > wrote: > > > > > Hi Michael, > > > > > > I actually side with your sentiment about the spec-first approach, but > > let > > > me clarify my concern here. > > > > > > Specs should certainly be developed before implementation is finalized. > > > > > > However, automating server-side code generation from the OpenAPI yaml has > > > some technical awkwardness (as I described in my fist email on this > > > thread). > > > > > > The alternative I'm proposing here is to avoid the intermediate stub > > > generation step and code endpoint implementation to match the existing > > > Iceberg REST API spec by leverating annotations and support from the > > > framework (Quarkus). > > > > > > I believe this approach provides more flexibility on the implementation > > > side and the amount of hand-written code is roughly the same whether we > > use > > > generated stubs or not. > > > > > > Compliance with the Iceberg spec is to be validated by running TCK / > > > Integration tests in CI. The integration tests could still use Iceberg > > > OpenAPI yaml for generating clients in whatever language is convenient > > for > > > them. Compliance tests are required even with generated server stubs, > > > because we cannot be completely sure the generated code is correct. > > > > > > Using different / more advanced tooling for server stub generation is > > going > > > to require more effort than manually adjusting java annotations to match > > > Iceberg spec changes. My assessment of this is grounded in the fact that > > > current hand-written code in Polaris has to adjust to spec changes in any > > > case. Any behaviour changes will require a thought process to adjust > > > server-side implementations, this part is hardly automatable in the > > current > > > Polaris build framework. > > > > > > When we're talking about Polaris' own APIs (Management, Generic Tables) > > we > > > could generate the Open API yaml from the endpoint annotations, as Robert > > > suggested. With this approach we can still review and settle on the spec > > > before implementation is plugged in. The only conceptual difference is > > that > > > the "source" for the spec will be code annotations (java) rather than > > > OpenAPI yaml. > > > > > > That said, we can probably consider moving the spec "source" to java > > > annotations as stage two, if the community is fine with removing > > generated > > > server stubs in general. > > > > > > WDYT? > > > > > > Thanks, > > > Dmitri. > > > > > > On Sat, Feb 14, 2026 at 1:25 PM Michael Collado <[email protected]> > > > wrote: > > > > > > > While I’m not particular about the tools, I’m pretty strongly in favor > > of > > > > the spec first approach. While the management APIs have the freedom to > > be > > > > code-first, the Iceberg catalog APIs are subject to a spec outside of > > our > > > > control. Adding in tools later to ensure compatibility feels > > > unnecessarily > > > > complex and just adds another thing we have to know about and maintain. > > > I’d > > > > be in favor of evaluating simpler, less verbose generators. > > > > > > > > Mike > > > > > > > > On Fri, Feb 13, 2026 at 2:25 PM Romain Manni-Bucau < > > > [email protected]> > > > > wrote: > > > > > > > > > What about moving to JSON-B? 🤔 > > > > > I know it can look like it misses fun feature but there is no > > technical > > > > > reason you don't manage to do all you want with it. > > > > > Will be more consistent with microprofile and more future friendly > > IMHO > > > > for > > > > > the project. > > > > > > > > > > Romain Manni-Bucau > > > > > @rmannibucau <https://x.com/rmannibucau> | .NET Blog > > > > > <https://dotnetbirdie.github.io/> | Blog < > > > https://rmannibucau.github.io/ > > > > > > > > > > | Old > > > > > Blog <http://rmannibucau.wordpress.com> | Github > > > > > <https://github.com/rmannibucau> | LinkedIn > > > > > <https://www.linkedin.com/in/rmannibucau> | Book > > > > > < > > > > > > > > > > > > > > https://www.packtpub.com/en-us/product/java-ee-8-high-performance-9781788473064 > > > > > > > > > > > Javaccino founder (Java/.NET service - contact via linkedin) > > > > > > > > > > > > > > > Le ven. 13 févr. 2026 à 16:03, Alexandre Dutra <[email protected]> a > > > > > écrit : > > > > > > > > > > > Hi Robert, > > > > > > > > > > > > Good point about Jackson 3, I agree that we should migrate ahead of > > > > > > Quarkus if possible, and that a code-first approach would make > > things > > > > > > easier. > > > > > > > > > > > > That said, it seems that support for Jackson 3 is now deferred to > > > > Quarkus > > > > > > 4 [1]. > > > > > > > > > > > > Thanks, > > > > > > Alex > > > > > > > > > > > > [1]: https://github.com/quarkusio/quarkus/issues/52036 > > > > > > > > > > > > On Fri, Feb 13, 2026 at 3:18 PM Robert Stupp <[email protected]> > > wrote: > > > > > > > > > > > > > > Another aspect, although strictly speaking unrelated, is Jackson > > 3. > > > > All > > > > > > > custom Jackson 2 serializers are incompatible with Jackson 3, and > > > > some > > > > > > > annotations are different. It is possible to use both Jackson 2 > > + 3 > > > > > > > annotations in the "code first" approach, and it works fine with > > > > > > Immutables. > > > > > > > > > > > > > > I'd expect Jackson 3 to become a necessity in the near future. > > For > > > > > > Quarkus, > > > > > > > it was already on the list of ideas for 3.31, but thankfully > > moved > > > > out. > > > > > > > A "code first" approach would save us that headache in the JAX-RS > > > > > > context. > > > > > > > > > > > > > > Side note: it's possible to use both Jackson 2 and Jackson 3 in > > the > > > > > same > > > > > > > code base - they can work side by side. > > > > > > > > > > > > > > > > > > > > > On Fri, Feb 13, 2026 at 3:00 PM Jean-Baptiste Onofré < > > > > [email protected]> > > > > > > > wrote: > > > > > > > > > > > > > > > Hi Dmitri, > > > > > > > > > > > > > > > > Thanks for starting this discussion. > > > > > > > > > > > > > > > > While I have a preference for the code-first approach, I wonder > > > if > > > > we > > > > > > can > > > > > > > > easily support the Iceberg REST Spec using this method. I would > > > > like > > > > > > to use > > > > > > > > JaxRS annotations, but it might be tricky to cleanly leverage > > the > > > > > > Iceberg > > > > > > > > REST Spec. > > > > > > > > > > > > > > > > Just my $0.01 > > > > > > > > > > > > > > > > Regards, > > > > > > > > JB > > > > > > > > > > > > > > > > On Thu, Feb 12, 2026 at 5:04 PM Dmitri Bourlatchkov < > > > > > [email protected]> > > > > > > > > wrote: > > > > > > > > > > > > > > > > > Hi All, > > > > > > > > > > > > > > > > > > I believe OpenAPI (REST) interface definitions that Polaris > > > > > provides > > > > > > are > > > > > > > > > very useful for end users and machine clients. > > > > > > > > > > > > > > > > > > However, I see that server-side code generation leads to > > > > > duplication > > > > > > > > > between generated code and hand-written code. For example, > > > > > > > > > `PolarisCatalogsApi` is generated, but most of the method > > > > > signatures > > > > > > in > > > > > > > > > `PolarisServiceImpl` have to be written by hand to match the > > > > > > generated > > > > > > > > > code. > > > > > > > > > > > > > > > > > > I wonder what people think about using direct hand-written > > > > service > > > > > > > > classes > > > > > > > > > to connect to REST endpoints via Rs-Api (Jakarta) > > annotations? > > > > > > > > > > > > > > > > > > I can see that generating service stubs might appear helpful > > to > > > > > > ensure > > > > > > > > that > > > > > > > > > all API endpoints have code that matches OpenAPI specs. > > > However, > > > > we > > > > > > have > > > > > > > > to > > > > > > > > > make tests to verify correct behaviour anyway. Those tests > > > could > > > > be > > > > > > made > > > > > > > > > with a generated client and will automatically ensure correct > > > > > > > > hand-written > > > > > > > > > code assuming coverage is good. > > > > > > > > > > > > > > > > > > WDYT? > > > > > > > > > > > > > > > > > > Thanks, > > > > > > > > > Dmitri. > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > > >
