Principle:Treeverse LakeFS Java SDK OpenAPI Specification
| Knowledge Sources | |
|---|---|
| Domains | API, SDK Generation, Java |
| Last Updated | 2026-02-08 00:00 GMT |
Overview
lakeFS uses an OpenAPI 3.0 specification as the single source of truth for its HTTP API, from which the Java SDK client is automatically generated to ensure consistency between server and client.
Description
The principle of specification-driven SDK generation dictates that the API contract is defined declaratively in an OpenAPI specification file before any client code is written. The lakeFS project maintains a comprehensive openapi.yaml file (version 1.0.0, served at /api/v1) that defines every endpoint, request/response schema, authentication method, and error contract. This specification is then fed into an automated code generator to produce the Java SDK, ensuring that:
- The client always matches the server's API surface exactly
- API changes are reflected in the SDK automatically upon regeneration
- Documentation, type safety, and validation are derived from the same source
- Multiple SDKs (Java, Python, Go, etc.) can be generated from the same spec
The OpenAPI spec supports five authentication schemes (JWT, basic, cookie, OIDC, SAML), uses JSON as the primary content type, and follows RESTful conventions with standard HTTP status codes and a shared Error schema for error responses.
Usage
Apply this principle whenever:
- The lakeFS HTTP API is modified or extended -- update the OpenAPI spec first, then regenerate client SDKs
- A new language SDK is needed -- use the same spec with a different generator target
- API documentation needs to be published -- generate it from the spec to keep it synchronized
- Breaking changes are introduced -- version the spec and generate compatibility-aware clients
- Validating API contracts in CI -- use the spec for contract testing between server and clients
Theoretical Basis
The specification-driven development approach is rooted in the design-first API methodology. By defining the API contract in a machine-readable format (OpenAPI/Swagger), the project achieves:
Contract-First Design: The API surface is agreed upon before implementation, reducing miscommunication between frontend and backend teams and between the server and its SDK consumers.
Code Generation: Tools like openapi-generator-cli parse the spec and produce type-safe client libraries. This eliminates manual SDK maintenance, reduces human error in serialization/deserialization code, and guarantees that every endpoint, parameter, and response type is correctly represented.
Single Source of Truth: Rather than maintaining the API definition in multiple places (server routes, client code, documentation), everything derives from one YAML file. Changes propagate mechanically, preventing drift.
Interoperability: The OpenAPI standard is widely supported. The same spec can generate clients in Java, Python, TypeScript, Go, and other languages, as well as produce interactive API explorers (Swagger UI), mock servers, and automated test suites.
In the lakeFS project, the spec at clients/java/api/openapi.yaml covers the full API surface including repository management, branch operations, object CRUD, commits, merges, action hooks, garbage collection, authentication setup, and access control, making it a comprehensive and authoritative contract.