Link Search Menu Expand Document (external link)

Kiota SDK Experience

Create a Resource

Basic read and write syntax for a resource.

// An authentication provider from the supported language 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 user = await client.Users["bob@contoso.com"].GetAsync();

var newUser = new User
{
    FirstName = "Bill",
    LastName = "Brown"
};

await client.Users.PostAsync(newUser);

Resources are accessed via relation properties starting from the client object. Collections of resources can be accessed by an indexer and a parameter. Once the desired resource has been referenced, the supported HTTP methods are exposed by corresponding methors. Deeply nested resource hierarchy can be accessed by continuing to traverse relationships.

// An authentication provider from the supported language 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["bob@contoso.com"]
                          .MailFolders["Inbox"]
                          .Messages[23242]
                          .GetAsync();

The client object is a request builder object, and forms the root of a hierarchy of request builder objects that can access any number of APIs that are merged into a common URI space.

Requests can be further refined by providing query parameters. Each HTTP operation method that supports query parameters accepts a lambda that can configure an object with the desired query parameters.

// An authentication provider from the supported language 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["bob@contoso.com"]
                          .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 make optional parameters easy to implement across languages.

Response with no schema

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 does not describe the response payload, then it should be assumed to be of content type application/octet-stream.

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


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

Warning: Support for stream responses identified by application/octet-stream are not supported yet

Response with simple schema

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

   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.

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

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

Warning: Support for text/plain responses are not supported yet

Filtered collection

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

   IEnumerable<Speaker> speakers = await apiClient.Speakers.GetAsync(x => { x.Location="Montreal"; });

Heterogenous collection

Kiota SDKs will automatically downcast heterogenous collection items (or single properties) to the target type if a discriminator is present in the description and if the response payload contains a matching mapping entry. This way SDK users can easily access the other properties available on the specialized type.

openapi: 3.0.3
info:
  title: Heterogenous 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

   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

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
  try {
   var speakersStream = await apiClient.Speakers.GetAsync();
  } 
  catch ( ServerException exception ) {
    Console.WriteLine(exception.Error.Message)
  } 

Warning: Support for ServerException is not supported yet