anguage table

// https://github.com/microsoft/kiota#supported-languages, or your own

implementation
var authProvider = ;
var requestAdapter = new HttpClientRequestAdapter(authProvider);
var client = new ApiClient(requestAdapter);
var message = await client.Users["[email protected]"]
.Events
.GetAsync(q =>
{ q.StartDateTime = DateTime.Now;
q.EndDateTime = DateTime.Now.AddDays(7);
});
Using a configured query parameter object prevents tight coupling on the order of
query parameters and makes optional parameters easy to implement across languages.

Response with no schema

YAML

Copy
openapi: 3.0.3
info:
title: The simplest thing that works
version: 1.0.0
servers:
- url: https://example.org/
paths:
/speakers:
get:
responses:
200:
description: Ok
If the OpenAPI description doesn't describe the response payload, then it should be
assumed to be of content type application/octet-stream.

Client library implementations should return the response payload in the language-
native way of providing an untyped set of bytes. This response format could be a
byte array or some kind of stream response.

C#

Copy
Stream speaker = await apiClient.Speakers.GetAsync();
Warning

Support for stream responses identified by application/octet-stream are not

supported yet

Response with simple schema

YAML

Copy
openapi: 3.0.3
info:
title: Response with simple schema
version: 1.0.0
servers:
- url: https://example.org/
paths:
/speakers/{speakerId}:
 get:
parameters:
- name: speakerId
in: path
required: true
schema:
type: string
responses:
200:
description: Ok
content:
application/json:
schema:
type: object
properties:
displayName:
type: string
C#

Copy
Speaker speaker = await apiClient.Speakers["23"].GetAsync();
string displayName = speaker.DisplayName;
Response with primitive payload
Responses with a content type of text/plain should be serialized into a primitive
data type. Unless a Schema object indicates a more precise data type, the payload
should be serialized to a string.

YAML

Copy
openapi: 3.0.3
info:
title: Response with primitive payload
version: 1.0.0
servers:
- url: https://example.org/
paths:
/speakers/count:
get:
responses:
200:
description: Ok
content:
text/plain:
schema:
type: number
C#

Copy
int speakerCount = await apiClient.Speakers.Count.GetAsync();
Warning

Support for text/plain responses are not supported yet

Filtered collection
YAML

Copy
openapi: 3.0.3
info:
title: Collection filtered by query parameter
version: 1.0.0
servers:
- url: https://example.org/
paths:
/speakers:
get:
parameters:
- name: location
in: query
required: false
schema:
type: string
responses:
200:
description: Ok
content:
application/json:
schema:
type: array
item:
$ref: "#/components/schemas/speaker"
components:
schemas:
speaker:
type: object
properties:
displayName:
type: string
location:
type: string
C#

Copy
IEnumerable<Speaker> speakers = await apiClient.Speakers.GetAsync(x =>
{ x.Location="Montreal"; });
Heterogeneous collection
Kiota client libraries automatically downcast heterogeneous collection items (or
single properties) to the target type if the following criteria are met. This way
client library users can easily access the other properties available on the
specialized type.

A discriminator is present in the description

The response payload contains a matching mapping entry.
YAML

Copy
openapi: 3.0.3
info:
title: Heterogeneous collection
version: 1.0.0
servers:
- url: https://example.org/
paths:
/sessions:
get:
parameters:
- name: location
 in: query
required: false
schema:
type: string
responses:
200:
description: Ok
content:
application/json:
schema:
type: array
item:
$ref: "#/components/schemas/session"
components:
schemas:
entity:
type: object
properties:
id:
type: string
session:
allof:
- $ref: "#/components/schemas/entity"
type: object
properties:
'@OData.Type':
type: string
enum:
- session
displayName:
type: string
location:
type: string
workshop:
allof:
- $ref: "#/components/schemas/session"
type: object
properties:
'@OData.Type':
type: string
enum:
- workshop
requiredEquipment:
type: string
presentation:
allof:
- $ref: "#/components/schemas/session"
type: object
properties:
'@OData.Type':
type: string
enum:
- presentation
recorded:
type: boolean

C#

Copy
IEnumerable<Session> sessions = await apiClient.Sessions.GetAsync();
List<Presentation> presentations = sessions.OfType<Presentation>().ToList();
// OfType is a native method that filters a collection based on the item type
returning a subset
Explicit Error Response
YAML

Copy
openapi: 3.0.3
info:
title: The simplest thing that works
version: 1.0.0
servers:
- url: https://example.org/
paths:
/speakers:
get:
responses:
"2XX":
description: Success
"4XX":
$ref: "#/components/responses/errorResponse"
"5XX":
$ref: "#/components/responses/errorResponse"
components:
responses:
errorResponse:
description: error
content:
application/json:
schema:
type: object
properties:
code:
type: string
message:
type: string
C#

Copy
try
{
var speakersStream = await apiClient.Speakers.GetAsync();
}
catch ( ServerException exception )
{
Console.WriteLine(exception.Error.Message)
}
Warning

Support for ServerException is not supported yet

Readability of the API client

Kiota is designed as a lightweight and fast API client generator that focuses on
the discovery, exploration, and calling of any HTTP API with minimal effort. The
primary goal of Kiota is to provide developers with a tool that simplifies the
process of working with APIs, rather than producing human-readable code. This
approach allows Kiota to support a wide range of languages and to handle the
complexities of all APIs efficiently. By keeping code readability as a non-goal,
Kiota can prioritize performance, scalability, and ease of use, ensuring that
developers can focus on the functionality of their applications rather than the
underlying auto-generated code.

Developers are encouraged to treat Kiota-generated code as an opaque box that

reliably handles API interactions. Peeking into the auto-generated code is
discouraged because it is optimized for machines, not human interpretation, which
could lead to confusion and misinterpretation. Instead, developers should utilize
the well-documented interfaces provided by Kiota to interact with their APIs. This
abstraction allows for a cleaner development experience and ensures that any
updates or changes to the Kiota generator do not impact the developer's workflow.
Trust in the robustness of Kiota's output allows developers to dedicate their time
to crafting the best possible applications with the assurance that the API
communication is handled efficiently in the background.