Hi all, The fundamental question here is whether we want a top-down or bottom-up approach to the REST API.
The bottom-up approach (or code-first, if you prefer) is appealing for many reasons, one of them being that we would be free to progressively migrate Polaris to an asynchronous/reactive execution model. But it also has its drawbacks, the biggest one being that we must comply with Iceberg's REST spec. This is easily achievable in a top-down approach – not so much in a bottom-up one. Both Robert's tool [1] and Dmitri's suggestion of specific tests with a generated client are good ways to fill the gap. I'm slightly in favor of the bottom-up approach, but playing devil's advocate, we could also explore the idea of keeping the top-down approach, but generating less code. We use a rather verbose generator today: "jaxrs-resteasy" (and with many custom templates). There are other generators that would generate e.g only the REST interface, and nothing else, e.g. the "jaxrs-spec" generator. Also, the polaris-api-management-model module today is entirely generated, but I think it could be made "code-first" even if we keep the top-down approach, since it only generates "model" classes – we could just as well write those pojos/records by hand. Just my 2 cents. Thanks, Alex [1]: https://github.com/apache/polaris/pull/3752 On Thu, Feb 12, 2026 at 9:13 PM Yufei Gu <[email protected]> wrote: > > I don't have a strong opinion on either side. I think the hand-written or > ai-writtern gives us more controls and less duplicates, we may just go with > it. > Yufei > > > On Thu, Feb 12, 2026 at 8:53 AM Romain Manni-Bucau <[email protected]> > wrote: > > > Hi > > > > +1 to be java first while it doesn't reach the runtime since it is totally > > useless to have these annotations, it must stay a build time generation and > > potentially the runtime can manipulate the openapi.json if needed (almost > > never but can be to filter by role). > > > > 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 jeu. 12 févr. 2026 à 17:24, Robert Stupp <[email protected]> a écrit : > > > > > Hi Dmitri, > > > > > > Thanks a lot for starting this discussion! > > > > > > There are many ways to verify whether an OpenAPI change > > > breaks backwards compatibility. > > > For Java types (and other things), there is revapi, which is relatively > > > simple to add to the Gradle build. The only downside is that it has to > > run > > > against a previously released version emitting the same "set of Java > > > types." Technically, revapi can check Java ABI compatibility of the > > current > > > state against a released artifact. > > > For OpenAPI specs there's a tool to compare two OpenAPI specs, it can be > > > configured in many ways, but most importantly to check whether there is a > > > breaking change. The tool can generate reports as Markdown and/or HTML, > > > which is quite helpful. It doesn't require a lot of work or code to get > > > that into the Polaris build. > > > With both checks in place (Java and OpenAPI), it would be pretty safe to > > > work "from the Java side" using Microprofile OpenAPI annotations, which > > BTW > > > works nicely with Immutables. > > > We can then even generate an OpenAPI spec from the Java types and still > > > generate (other) Java code from that. > > > > > > Robert > > > > > > > > > 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. > > > > > > > > >
