Skip to content

[NI][SDK] Add platform API generation input#102

Open
chris-freeman-glean wants to merge 6 commits intomainfrom
cfreeman/api-overhaul-pr19c-platform-speakeasy
Open

[NI][SDK] Add platform API generation input#102
chris-freeman-glean wants to merge 6 commits intomainfrom
cfreeman/api-overhaul-pr19c-platform-speakeasy

Conversation

@chris-freeman-glean
Copy link
Copy Markdown
Contributor

@chris-freeman-glean chris-freeman-glean commented May 8, 2026

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 operationId drives 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.query and platform-tools-list -> platform.tools.list, which generate client.platform.search.query(...) and client.platform.tools.list(...) while preserving source operation IDs.

Platform schemas and shared responses are prefixed, Platform auth is normalized to the existing APIToken scheme, 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.id and introduced for both endpoints but no longer include x-glean-experimental.gated-by. That stripping happens at the scio Redocly public-export boundary before these SDK artifacts are generated.

Cross-Repo Stack

  1. scio source contract and private metadata stripping: https://github.com/askscio/scio/pull/237884
  2. Redocly bundle publication: https://github.com/askscio/openapi-redocly/pull/15
  3. SDK spec transform and explicit SDK mapping: [NI][SDK] Add platform API generation input #102 (this PR)

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_specs
  • speakeasy run -s glean-api-specs --skip-upload-spec
  • pnpm vitest run tests/source-spec-transformer.test.js tests/post_transform_smoke.test.js
  • Verified gated-by is absent from source_specs/platform.yaml, generated_specs/platform.yaml, and overlayed_specs/glean-merged-spec.yaml, while experimental id and introduced remain for /api/search and /api/tools.
  • Verified transformed and merged specs contain /api/search as platform.search.query and /api/tools as platform.tools.list, with Platform-prefixed models and responses.

Add convention-driven Platform API transformation so flag-gated platform endpoints publish to SDKs with stable namespaces and collision-free models.
@chris-freeman-glean chris-freeman-glean force-pushed the cfreeman/api-overhaul-pr19c-platform-speakeasy branch from 778a166 to 7ba4009 Compare May 8, 2026 19:24
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.
@chris-freeman-glean chris-freeman-glean marked this pull request as ready for review May 8, 2026 22:16
@chris-freeman-glean chris-freeman-glean requested a review from a team as a code owner May 8, 2026 22:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants