Kiota¶

Stable

Kiota is a .NET tool for generating strongly-typed API client code from OpenAPI descriptions.

Property	Value
Current Version	1.x
Forge Compatibility	Forge 2.1+, Forge 3.0
Status	Stable

Description¶

Kiota is a .NET tool designed to generate client code for calling REST APIs from OpenAPI descriptions. It is part of the Microsoft Kiota project, which aims to simplify the process of consuming RESTful services by automating the generation of strongly-typed client libraries.

In the Forge ecosystem, Kiota works with TypeSpec to provide a contract-first API development workflow.

Why we use it¶

Kiota is used to generate .NET client code for calling APIs. It uses the OpenAPI file created with TypeSpec to create models and code to call the API.

Key benefits:

Type Safety - Generated clients provide compile-time type checking
Consistency - All API clients follow the same patterns
Reduced Boilerplate - No manual HTTP client code needed
Auto-updates - Regenerate when the API contract changes
Built-in Authentication - Integrates with SAIF.Platform.Kiota.HttpClientLibrary for automatic token handling

When to use it¶

✅ Consuming external APIs with OpenAPI specifications
✅ Creating clients for internal Forge APIs
✅ Contract-first development with TypeSpec

When NOT to use it:

❌ APIs without OpenAPI specifications
❌ Simple one-off HTTP calls (use HttpClient directly)

Quick Example¶

Generating a Client¶

Add a <KiotaReference> to your .csproj file:

<ItemGroup>
  <KiotaReference Include="DownstreamClient" OpenApi="https://openapi.saif.com/it-api-sys-downstream/test/openapi.v1.yaml">
    <NamespaceName>YourApp.Clients.Downstream</NamespaceName>
  </KiotaReference>
</ItemGroup>

Configuring Authentication¶

// Configure a Kiota client with authentication
builder.ConfigureHttpClient<DownstreamClient, TokenExchangeAccessTokenProvider>(
    "it-api-sys-downstream",
    options => options.Scopes = ["Client.Read"]);

// Use the client in your endpoint
app.MapGet("/data", async (DownstreamClient client) =>
{
    var result = await client.Resources.GetAsync();
    return Results.Ok(result);
});

For complete configuration details, see Calling Downstream APIs.

Prerequisites¶

.NET 10 SDK
OpenAPI specification file (typically generated from TypeSpec)
SAIF.Platform.Kiota.HttpClientLibrary package (included in Forge templates)

Version notes¶

Kiota 1.32.0+ and numeric default initialization¶

From Kiota 1.32.0 (microsoft/kiota#7404), generated models initialize numeric and boolean properties from their OpenAPI default value in the constructor (for example, Status = 400;).

The platform error models (BadRequest, NotFound, and the other TypeSpec ProblemDetails types) declare status only on the concrete error models, never on the shared ProblemDetails base. This avoids a parent/child property redundancy that Kiota would otherwise deduplicate — dropping the child status while still emitting its constructor initializer, which produces a CS0103: The name 'Status' does not exist in the current context compile error.

Regenerated clients gain a Status property

Because status now resolves to a real generated property, regenerated error models expose a public int? Status property. This is an additive, non-breaking change — earlier generated clients silently omitted it.

Guide	Description
Calling Downstream APIs	Configure Kiota clients with scopes and authentication
Security Configuration	Infrastructure-side auth configuration
TypeSpec	API contract definition that generates OpenAPI for Kiota
WireMock CLI Hosting	API mocking with Kiota client generation