GitHub user mchades added a comment to the discussion: Proposal: Adopt OpenAPI as the External Contract for Gravitino API V2
Thanks for putting together this thoughtful proposal. As one of the original contributors and maintainers of Gravitino’s OpenAPI module, I agree with the problem statement and support the overall direction of making OpenAPI the authoritative external contract for API V2. The current OpenAPI module was initially introduced mainly to document and manage REST API definitions. It was not designed as an executable source of truth or as the basis for server/client generation. Evolving it into a stronger contract is reasonable as Gravitino’s API surface and non-Java ecosystem grow. That said, I do not think the proposal is implementation-ready yet. It currently combines three related but distinct efforts: - Improving the quality and CI validation of the existing OpenAPI specification. - Fixing V1 error classification and HTTP semantics. - Designing a new contract-first V2 architecture. These efforts should be coordinated, but they should not block one another. In particular, important V1 error-handling improvements should not wait for V2. I also suggest keeping the model strategy open. Making OpenAPI authoritative does not necessarily require generating all request/response models or introducing a completely separate model hierarchy. For example, Apache Polaris generates JAX-RS service interfaces from OpenAPI while mapping schema types to Iceberg’s maintained REST models. Other approaches are also viable. We should validate the trade-offs before committing to one architecture. My recommendation is to start with a narrow Catalog/Table vertical slice and use it to answer the remaining design questions: - V1/V2 coexistence and version negotiation. - Generated interfaces versus generated or hand-written wire models. - The boundary between external models and existing DTO/domain models. - A stable public error model, including reason, domain, retryability, and request ID. - Code-generation checks for Java, Rust, and Python, without initially committing to officially supporting all generated SDKs. - Runtime conformance, customer-journey tests, and breaking-change detection. - Ownership and release lifecycle of the authoritative specification. Therefore, my position is **+1 on the direction and on starting a focused design/PoC**, but I would not yet treat the full V2 migration or translation-layer architecture as decided. A small end-to-end prototype should give us the evidence needed to make those decisions confidently. GitHub link: https://github.com/apache/gravitino/discussions/11999#discussioncomment-17617264 ---- This is an automatically sent email for [email protected]. To unsubscribe, please send an email to: [email protected]
