# Kiota

<span class="status stable">Stable</span>

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](typespec.md) 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](typespec.md) 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:

```xml
<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

```csharp
// 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](../../guides/development/calling-apis.md).

---

## 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](https://github.com/microsoft/kiota/pull/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](typespec.md) `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.

!!! note "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.

---

## Related Documentation

| Guide                                                               | Description                                              |
| ------------------------------------------------------------------- | -------------------------------------------------------- |
| [Calling Downstream APIs](../../guides/development/calling-apis.md) | Configure Kiota clients with scopes and authentication   |
| [Security Configuration](../../guides/security/index.md)            | Infrastructure-side auth configuration                   |
| [TypeSpec](typespec.md)                                             | API contract definition that generates OpenAPI for Kiota |
| [WireMock CLI Hosting](../../foundry/aspire-wiremockcli.md)         | API mocking with Kiota client generation                 |

---

## Links

- [Kiota Overview](https://learn.microsoft.com/en-us/openapi/kiota/overview)
- [Install Kiota CLI](https://learn.microsoft.com/en-us/openapi/kiota/install?tabs=bash#install-as-net-tool)