[NI][SDK] Add platform API generation input#102
Open
chris-freeman-glean wants to merge 6 commits intomainfrom
Open
[NI][SDK] Add platform API generation input#102chris-freeman-glean wants to merge 6 commits intomainfrom
chris-freeman-glean wants to merge 6 commits intomainfrom
Conversation
Add convention-driven Platform API transformation so flag-gated platform endpoints publish to SDKs with stable namespaces and collision-free models.
778a166 to
7ba4009
Compare
Move Platform SDK method naming into an explicit open-api mapping so scio operationIds remain server-oriented.
Document how Platform operation mappings translate into generated SDK method chains.
Document why Platform specs are namespaced, auth-normalized, and explicitly mapped before SDK generation.
Regenerate the public Platform specs from the stripped bundle so SDK publishing no longer exposes internal feature flag names.
Extend the explicit Platform SDK mapping and regenerated specs so the publishing path covers both search and tools endpoints.
travis-hoover-glean
approved these changes
May 8, 2026
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Why
The new Platform API surface needs to publish into generated SDKs without leaking SDK naming policy into scio's source OpenAPI specs. Scio's
operationIddrives Go server codegen and should remain a stable server/API identity; the SDK publishing repo should own the public SDK namespace and method shape.The SDK repo also merges several OpenAPI specs together, so Platform schemas and shared responses need deterministic namespacing to avoid collisions with the existing REST and indexing contracts. Public SDK inputs also must not expose scio runtime config details such as feature flag names.
What Changes
This PR adds Platform API as an SDK generation input and introduces a Platform transform that explicitly maps scio operation IDs to SDK names. The current mappings are
platform-search -> platform.search.queryandplatform-tools-list -> platform.tools.list, which generateclient.platform.search.query(...)andclient.platform.tools.list(...)while preserving source operation IDs.Platform schemas and shared responses are prefixed, Platform auth is normalized to the existing
APITokenscheme, and unmapped Platform operations or namespace collisions fail during transform instead of silently producing a broken merged spec. There is no Platform overlay file in this PR; the default path is transform-driven and the SDK surface is reviewed through the explicit mapping.The regenerated Platform public specs preserve
x-glean-experimental.idandintroducedfor both endpoints but no longer includex-glean-experimental.gated-by. That stripping happens at the scio Redocly public-export boundary before these SDK artifacts are generated.Cross-Repo Stack
Merge order should follow the stack above so this repo consumes the Platform bundle produced by the previous steps.
Test Plan
pnpm run transform:source_specsspeakeasy run -s glean-api-specs --skip-upload-specpnpm vitest run tests/source-spec-transformer.test.js tests/post_transform_smoke.test.jsgated-byis absent fromsource_specs/platform.yaml,generated_specs/platform.yaml, andoverlayed_specs/glean-merged-spec.yaml, while experimentalidandintroducedremain for/api/searchand/api/tools./api/searchasplatform.search.queryand/api/toolsasplatform.tools.list, with Platform-prefixed models and responses.