Modifier

Kiota API client experience

  • Article

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 methods. 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"; });

Heterogeneous collection

Kiota SDKs will automatically downcast heterogeneous 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: 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


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