feat: generate OpenAPI clients with per-module API versions #580
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Update the codegen script (build-oas.sh) to support per-module API version and branch configuration. This enables generating db_control and db_data clients from the alpha API spec (2026-01.alpha) while keeping inference, oauth, and admin on the stable spec (2025-10). Key changes: - Refactor build-oas.sh to use functions for version/branch lookup - Generate db_control and db_data from 2026-01.alpha spec - Generate inference, oauth, admin from 2025-10 spec - Update api_version.py to use alpha version for gRPC compatibility - Add conditional file checks for underscore manipulation The alpha API introduces a new schema-based index creation model with "deployment" and "schema" fields replacing the legacy "spec" approach. This is a breaking change from the stable API - subsequent SDK updates (SDK-101 through SDK-115) will add compatibility layers. Resolves SDK-99
The alpha API has breaking changes from the stable API structure. Linting and unit tests will fail until SDK compatibility work (SDK-104 through SDK-107) is complete. This matches the existing behavior for integration tests which are already skipped for fts-targeted PRs. See SDK-116 for re-enabling tests after compatibility work.
jhamon
added
enhancement
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
Address Bugbot feedback: - Remove redundant current_apis_branch tracking (processed_branches already handles deduplication in the main loop) - Replace get_module_branch() function with APIS_BRANCH constant since all modules currently use the same branch
Since all modules use the same APIS_BRANCH constant, move the checkout_and_build_apis call before the module loop and remove the unnecessary processed_branches tracking.
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.
| from __future__ import annotations | ||
|
|
||
| from typing import TYPE_CHECKING, Any, Dict, cast | ||
| from typing import TYPE_CHECKING |
There was a problem hiding this comment.
Unused TYPE_CHECKING import in generated API files
Low Severity
The TYPE_CHECKING constant is imported from typing but is never used in these files. There is no if TYPE_CHECKING: block anywhere in the file - TYPE_CHECKING only appears in the import statement itself. This affects api_keys_api.py, organizations_api.py, projects_api.py, manage_indexes_api.py, and bulk_operations_api.py. The PR changed the import from from typing import TYPE_CHECKING, Any, Dict, cast to from typing import TYPE_CHECKING, removing cast usage but leaving the unused TYPE_CHECKING.
Additional Locations (2)
jhamon
deleted the
jhamon/sdk-99-generate-openapi-client-for-2026-01alpha-api
branch
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Updates the OpenAPI codegen script to support per-module API version and branch configuration, enabling:
db_controlanddb_datato use the 2026-01.alpha spec from thejhamon/ftsbranchinference,oauth, andadminto remain on the 2025-10 stable specProblem
The Full-Text Search (FTS) feature requires new API endpoints and models that are only available in the alpha API spec. The existing codegen script only supports a single API version for all modules, making it impossible to incrementally adopt the alpha API.
Solution
Refactored
build-oas.shto:get_module_version,get_module_branch) for per-module configurationapi_version.pyto use the db_data version (for gRPC compatibility)API Version Configuration
Breaking Changes
The alpha API has a fundamentally different structure:
specwithServerlessSpec,PodSpec,ByocSpecdeploymentwithServerlessDeployment,PodDeployment,ByocDeploymentand aschemafieldThe existing SDK code references models that don't exist in the alpha spec. This is expected - subsequent tickets (SDK-101 through SDK-115) will add compatibility layers and update the SDK to work with the new API structure.
New Models in Alpha Spec
db_control:
Deployment,ServerlessDeployment,PodDeployment,ByocDeploymentSchema,SchemaFieldsdb_data:
Document,DocumentSearchRequest,DocumentSearchResponseDocumentUpsertRequest,DocumentUpsertResponseTextQuery,VectorQuery,ScoreByQueryTesting
__init__.pyRelated
Note
Introduces per-module OpenAPI versioning and regenerates clients to adopt the alpha spec where needed.
codegen/build-oas.shto use per-module versions (db_control/db_data->2026-01.alpha, others remain2025-10), checkoutapisonjhamon/fts, verify each version once, and writepinecone/openapi_support/api_version.pyusing thedb_dataversion; makes underscore-fix step conditionaldb_controlmoves to2026-01.alpha(newschema/deployment/read_capacitystructures; addsByocDeployment; updates models likeBackupModel,ConfigureIndexRequest,CreateIndexForModelRequest; updates method docs and defaultX-Pinecone-Api-Version);adminclients get minor typing cleanup (removecast/unused imports).github/workflows/on-pr.yaml, skiplintingandunit-testswhen PR base isftsWritten by Cursor Bugbot for commit 6a28437. This will update automatically on new commits. Configure here.