Kiota SDK Builder

This page is a single canonical reference for the full Microsoft Kiota SDK workflow. Use the interactive Build My SDK workflow above while you read, or jump to a topic below.

Microsoft Kiota is an OpenAPI-driven SDK generator that produces strongly typed API clients. Unlike hand-written HTTP wrappers, Kiota emits a consistent request builder model: navigate from a root client to path segments, attach query parameters, and call fluent methods that return typed responses.

Supported languages (Kiota 1.x)

• C#, Go, Java, JavaScript/TypeScript, PHP, Python, Ruby, and Swift
• Same OpenAPI input with language-specific idioms (e.g. snake_case modules in Python)

Use Kiota when

• Building clients for Microsoft Graph, Azure APIs, or any OpenAPI 3.x document
• You want consistent request builders, pagination helpers, and typed models across languages
• You need a unified authentication abstraction via Kiota Abstractions and auth provider packages

Skip Kiota when

• Your API is not described by OpenAPI
• You need server-side code generation only
• Your team standardizes on NSwag (.NET) or OpenAPI Generator (broad template ecosystem)

This DevUtilities workspace validates spec readiness, previews SDK structure, compares generators, configures auth, and exports ready-to-run kiota generate commands—all without uploading your spec to a server.

Compare OpenAPI client generators before you commit to a toolchain. The Compare Generators tab on this page estimates file count and generation time for your uploaded spec.

Kiota 1.x supports C#, Go, Java, JavaScript/TypeScript, PHP, Python, Ruby, and Swift from the same OpenAPI document.

• TypeScript/JavaScript: ES modules with a Kiota request adapter
• C#: integrates with Microsoft.Kiota.Abstractions
• Python: snake_case module layout
• Reserved keywords: Kiota applies language-specific escaping when model names collide

Not every OpenAPI feature maps identically to every language—discriminated unions may flatten differently in Go versus TypeScript. Use the Multi-Language preview tab before generating.

Kiota requires OpenAPI 3.0 or 3.1 with at least one path and operation. Aim for four or five stars in the readiness score before running kiota generate in CI.

High-quality spec checklist

• Unique operationId on every operation
• Explicit schema titles for reusable components
• servers entry or a --base-url for the CLI
• securitySchemes under components, referenced on operations
• Response content schemas (not empty {}) for typed deserialization

What this tool checks

• Duplicate or missing operationIds
• Missing response schemas and circular $ref chains
• Polymorphism without discriminator
• Nullable style mismatches between OpenAPI 3.0 and 3.1

Fix syntax errors with the OpenAPI Validator tool first, then return here for Kiota-specific compatibility.

Why it happens

OpenAPI allows omitting operationId, but Kiota uses it to name request builder methods. Duplicate or colliding IDs cause generation failures or silent method overwrites.

Diagnose

Search your spec for duplicate operationId strings, or identical path/method combinations after normalization.

Fixes

1. Assign globally unique operationId values (e.g. users_list_v1 following resource_action_version).
2. Fix the source spec if you control the API; otherwise post-process with a rename script.
3. Use --include-path trimming flags to generate a subset while fixing upstream.

Best practice: enforce unique operationIds in Spectral or your API design linter before publishing.

Why it happens

JSON Schema $ref cycles (A → B → A) confuse serializers and may cause Kiota to abort model generation.

Diagnose

The diagnostics panel flags circular component chains. Swagger UI also reveals self-referential types (e.g. TreeNode with TreeNode[] children).

Fixes

1. Break the cycle by inlining one side or introducing a shallow DTO for generation.
2. Replace unbounded recursive models with depth-limited variants for client use.
3. For polymorphic graphs, use discriminator-based oneOf instead of unchecked object loops.

Kiota supports some recursive types in newer versions, but shallow specs remain more portable across languages.

Why it happens

OpenAPI 3.0 uses nullable: true while 3.1 uses type unions like [string, null]. Mixing styles produces inconsistent nullability in C# and TypeScript.

Diagnose

Inspect components.schemas for inconsistent nullable markers. Verify required arrays—required means the key must appear, not that the value is non-null.

Fixes

1. Standardize on OpenAPI 3.1 type unions or consistent nullable: true across schemas.
2. Mark optional fields correctly in required arrays.
3. Regenerate after normalizing so each language adapter maps nullability correctly.

The OpenAPI Readiness panel highlights nullable mismatches that break strict TypeScript builds.

Kiota clients do not embed secrets—they accept an authentication provider on the request adapter. Match the scheme name in OpenAPI (BearerAuth, oauth2) to your provider template.

Common patterns

• Bearer / OAuth 2.0: IAccessTokenProvider or Azure Identity with Microsoft Graph
• API key: custom provider setting x-api-key header or query params per security scheme
• OAuth authorization code: acquire tokens out-of-band; provider returns cached tokens
• Microsoft Graph multi-tenant: ClientSecretCredential, DeviceCodeCredential, or InteractiveBrowserCredential

The Auth step in this workflow maps your spec's securitySchemes to starter TypeScript and C# snippets. Never commit client secrets—load from environment variables or a vault at runtime.

Large APIs like Microsoft Graph contain thousands of operations; most apps need a slice. Trimming reduces compile time, package size, and review noise.

CLI flags

• --include-path and --exclude-path accept glob patterns (e.g. /users/**, !/admin/**)
• Exported kiota generate commands include --include-path when you select endpoints here

Workflow

1. Load the full spec
2. Select only tags or paths your app calls
3. Preview SDK tree size in the Preview step
4. Copy the CLI command and run locally
5. Document trim patterns in your repo for consistent CI regeneration

Treat generated clients as build artifacts—avoid hand-editing generated files. Regeneration overwrites manual patches.

1. Generate into a dedicated folder (./generated/sdk) and wrap with your own facade for business logic
2. Use partial classes (C#) or module augmentation (TypeScript) outside generated paths
3. Store kiota-lock.json and pin Kiota CLI version in git; regenerate in CI so drift is visible in diffs
4. If you must fork, namespace the output directory and merge via git subtrees only when upgrading Kiota

The Generate step shows sample usage code and output layout you can commit as a baseline.

1. Download spec: fetch Microsoft Graph OpenAPI metadata or use trimmed Graph beta JSON in your repo
2. Trim paths: include only /me, /users, /groups your app needs
3. Generate: kiota generate -l typescript -d graph.json -o ./src/graph-sdk -c GraphClient --base-url https://graph.microsoft.com/v1.0
4. Authenticate: TokenCredentialRequestAdapter with @azure/identity DefaultAzureCredential or on-behalf-of for web apps
5. Call API: const user = await client.me.get(); handle OData errors via Graph error model
6. Handle errors: 401 → refresh tokens; 429 → respect Retry-After; add Kiota retry middleware as needed

This tool's workflow mirrors these steps with readiness analysis for Graph-scale specs.

GitHub REST

• Download OpenAPI from GitHub's published description
• Generate with --base-url https://api.github.com
• Authenticate with Bearer PAT via custom access token provider
• Trim to repos and pulls paths—the full spec is large

Stripe

• Stripe publishes OpenAPI—generate TypeScript for customers and payment intents
• Use Bearer sk_test_... from environment variables; never embed keys
• Verify discriminated schemas for polymorphic objects (payment_method types) in readiness panel

Petstore (smoke test)

Use openapi.json from learn.openapis.org to preview the full SDK tree and compare generator timings without trimming.

Pin Kiota CLI version in CI for reproducible builds: dotnet tool install Microsoft.OpenApi.Kiota --version x.y.z

Typical pipeline

1. Lint OpenAPI with Spectral
2. Run kiota validate or this readiness check
3. kiota generate into src/generated
4. Commit kiota-lock.json when used
5. Run language tests against mock server or recorded fixtures
6. Fail PR if git diff is non-empty after generation

For monorepos, generate per API package in parallel jobs. Store the spec as source of truth—client drift means the spec changed without regeneration.

Generation time and output size scale with operation count and schema depth.

• Graph-scale specs (10k+ operations): minutes and thousands of files—trim aggressively
• Memory: Kiota loads the full document; split multi-megabyte specs if CLI runs out of memory
• Compile time: smaller SDKs mean faster tsc and smaller npm packages

Rule of thumb (public specs)

• Petstore: ~1s, under 50 files
• Medium internal APIs: ~5–30s
• Graph-scale: path filtering required for acceptable developer experience

DevUtilities estimates generation seconds and file counts from your spec so you can benchmark before local runs.

• Split specs by bounded context—separate packages for billing vs identity
• Use tags consistently so Kiota grouping matches team ownership
• Prefer components.schemas over inline anonymous objects
• Add operationId early in API design
• Version paths (/v1, /v2) and generate separate clients per major version
• Run readiness checks on every PR that touches the spec
• Centralize security schemes
• Strip x-internal endpoints in a build step before generate when generators cannot filter extensions

1. Refresh OpenAPI spec from source when the API changes
2. Diff the spec (openapi-diff or oasdiff)
3. Regenerate the client and review git diff for breaking renames
4. Treat operationId as a public contract—Kiota renames methods when operationId changes
5. Additive changes (new optional properties) are usually safe; removed operations fail compile early
6. Version spec in semver; tag generated releases to match
7. Update kiota-lock.json after intentional Kiota CLI upgrades
8. Communicate SDK updates via changelog entries derived from spec diff

• Clients only—Kiota does not generate server stubs
• Partial support: complex oneOf/allOf may simplify; callbacks and webhooks often skipped
• Binary formats may map to streams differently per language
• Weak typings when schemas are mostly untyped JSON blobs—improve at source
• Kiota cannot invent operationIds—you must supply or accept derived names
• WebSocket APIs are out of scope

When Kiota cannot model an edge case, fall back to raw fetch for that endpoint or post-process with wrapper methods. Watch Kiota release notes when upgrading.