Feature Request: Machine-Readable Documentation in Dremio

Tl;dr: a Dremio API specification adehering to OpenAPI standards.

While Dremio already provides extensive documentation for its client endpoints (https://docs.dremio.com/), there is a significant opportunity to further enhance the integration and adoption of Dremio within the data engineering ecosystem. One essential component that is currently missing is a machine-readable documentation format.

In recent years, the adoption of machine-readable documentation formats, such as the OpenAPI project (Introduction | OpenAPI Documentation), has become increasingly prevalent. These formats allow APIs to be described in a standardized manner that is both human and machine-readable. By embracing this trend and implementing a machine-readable catalog of Dremio’s client endpoints and their corresponding JSON schemas, Dremio can unlock a range of benefits.

First and foremost, a machine-readable documentation format would greatly simplify the process of creating contract-first integrations with Dremio. Developers could effortlessly generate client code, perform automatic validation of API responses, and ensure compatibility with other tools and frameworks. This standardized approach significantly reduces development time and effort, enabling faster and more robust integrations.

Moreover, a machine-readable catalog provides a clear and unambiguous representation of the API surface area. Developers can easily explore and understand the available endpoints, their parameters, and the expected responses. This promotes self-service integration and empowers developers to leverage Dremio’s capabilities without extensive manual documentation referencing.

Furthermore, a machine-readable format enhances interoperability within the data engineering ecosystem. By providing a clear specification of the API contract, Dremio becomes more compatible with other tools, frameworks, and platforms that support the OpenAPI standard. This opens up opportunities for seamless integration, enabling users to leverage Dremio alongside their existing toolset.

In conclusion, implementing a machine-readable catalog of Dremio’s client endpoints and JSON schemas would be a strategic decision that aligns with the industry’s best practices. By embracing this approach, Dremio can attract a broader audience of developers, improve integration capabilities, and foster collaboration within the data engineering community. I strongly believe that this feature would be instrumental in propelling Dremio to new heights as a leading platform in the data engineering domain.

I kindly request your consideration and support in implementing this enhancement. A machine-readable API catalog or a complete set of JSON schema of the response objects could greatly reduce the amount of boilerplate code is needed to be written to marshal a Dremio client response.