DOCSEARCHbyAlgolia
Submit Docs

Kiota

repository·main·Indexed 26 days ago

https://github.com/microsoft/kiota

A command-line tool and Visual Studio Code extension that generates strongly typed API clients, plugins, and manifests from OpenAPI descriptions. Kiota provides language-specific abstraction, authentication, HTTP, and serialization libraries for Dotnet, Go, Java, PHP, Python, Ruby, and TypeScript, allowing developers to interact with OpenAPI-compliant APIs without installing service-specific SDKs.

Tokens
18.2K
Snippets
39
Records
122
Agent score
82%

What's inside Kiota

  1. Overview of Kiota Authentication libraries

    main

    Kiota Authentication libraries are language-specific implementations of the authentication interfaces required by Kiota-generated SDKs. Once you have generated an SDK from an OpenAPI definition, you must include the corresponding authentication library for your language to authenticate requests before calling the API.

    To build and run your project, you will need a reference to the abstraction package for your specific language.

  2. Overview of Kiota HTTP libraries

    main
    Kiota HTTP libraries are language-specific implementations of the interfaces required by Kiota-generated SDKs to execute HTTP requests. When using a Kiota-generated SDK, your project must include a reference to the corresponding abstraction package for your chosen language to build and run successfully.

  3. Overview of Kiota

    main
    Kiota is a command-line tool designed to generate API clients for any API described by an OpenAPI specification. It aims to eliminate the need for managing multiple different SDKs by providing a consistent, strongly typed experience for calling various HTTP APIs. Kiota leverages the Microsoft.OpenAPI.NET library to ensure robust support for OpenAPI and JSON Schema features.

  4. Overview of Kiota

    main

    Kiota is a client, plugin, and manifest generator for HTTP REST APIs described by OpenAPI. It can be used as a command-line tool or via a Visual Studio Code extension.

    Key capabilities include:

    • Searching for API descriptions.
    • Filtering and selecting specific API endpoints from OpenAPI descriptions to reduce bloat.
    • Generating models and chained method API surfaces in various supported languages.
    • Generating API plugin manifests for integration into Microsoft Copilot.
    • Generating API manifests.

  5. Use Kiota language-specific abstraction libraries

    main

    Kiota abstractions are language-specific libraries that define the basic constructs required by a Kiota-generated SDK. To build and run an SDK generated from an OpenAPI definition, your project must include a reference to the corresponding abstraction package for your target language.

    Supported languages and their abstraction repositories include:

    • Dotnet
    • Go
    • Java
    • PHP
    • Python
    • Ruby
    • TypeScript

  6. Kiota CLI Command Reference Overview

    main
    The Kiota CLI provides a comprehensive set of commands for managing API clients, plugins, workspaces, and authentication. Use these commands to generate SDKs, manage your local development environment, and interact with the Kiota ecosystem.

  7. Understand Kiota telemetry data collection

    main

    Kiota collects non-sensitive usage data to understand community needs and prioritize features.

    Basic data collected for every command:

    • Timestamp
    • Operating system and version
    • Source (CLI or extension)
    • Acquisition channel (e.g., dotnet tool, binaries, homebrew, asdf, extension)
    • Kiota version
    • VS Code extension version (if applicable)
    • Command name
    • Command parameters being used (names only, no sensitive values)
    • Command execution time
    • Command result (success or failure)

    Privacy Guarantees:

    • No personally identifiable information (PII) is collected.
    • No information about the specific API being used is collected.
    • No information about the application using the API is collected.
    • No telemetry is collected during the runtime of the generated application.

  8. Understand the Kiota workspace file structure

    main

    When using Kiota, the following directory structure is managed to track clients, documents, and generated code:

    • .kiota/workspace.json: Contains the configuration for all registered API clients.
    • .kiota/apimanifest.json: An API Manifest representing a snapshot of API dependencies and permissions.
    • .kiota/documents/{client-name}/: Stores local copies of the OpenAPI descriptions (YAML/JSON).
    • {output-path}: The directory where your generated SDK code resides.
    /
 └─.kiota
    └─apimanifest.json
    └─workspace.json 
    └─documents
       └─GraphClient
         └─GraphClient.yaml
 └─generated
    └─graph
       └─csharp
          └─... # Generated code files
          └─GraphClient.cs

  9. Understand the file structure after adding a plugin

    main

    When you run kiota plugin add, Kiota generates a specific directory structure to manage your workspace, API manifests, and generated plugin artifacts.

    • .kiota/workspace.json: The main configuration file for your Kiota workspace.
    • .kiota/apimanifest.json: A single artifact containing all API dependencies across all clients and plugins.
    • .kiota/documents/<plugin-name>/: Contains the original OpenAPI document and any overlays.
    • <output-directory>/<plugin-name>/:
      • <plugin-name>-apimanifest.json: The specific API Manifest for the plugin.
      • <plugin-name>-apiplugin.json: The API Plugin definition.
      • <plugin-name>-openapi.json: The sliced and augmented OpenAPI document.
     └─.kiota
    └─workspace.json
    └─apimanifest.json # Single artifact with all APIs dependencies info across clients and plugins
    └─documents
      └─github    
        └─openapi.json # OpenAPI document
        └─overlay.json # Overlay to be applied on top of OpenAPI document
 └─generated
    └─plugins
      └─github
          └─github-apimanifest.json # Specific API Manifest
          └─github-apiplugin.json #API Plugin
          └─github-openapi.json # Sliced and augmented OpenAPI document

  10. Generate an API client using the Kiota VS Code extension

    main

    Follow these steps to generate an API client within VS Code:

    1. Add API Description: Use the 'add file' icons in the extension UI or open the Command Palette and run the command Add API description.
    2. Search/Browse: Search for an API using keywords. Results will appear in the search results view.
    3. Select OpenAPI Description: Choose the desired OpenAPI description to open the Kiota OpenAPI Explorer.
    4. Filter Endpoints: Select the specific endpoints you want to include in your client.
    5. Generate: Click the generate icon. Choose your generation target (e.g., client, plugin, or other).
    6. Verify: A notification "Generation Completed Successfully" will appear. You can find the output in your current workspace or the selected output folder.

  11. Understand API Manifest generation

    main

    Kiota manages two types of API Manifests:

    1. Global API Manifest: Located at ./kiota/apimanifest.json. This represents the concatenated surface of all API dependencies across all clients and plugins in the workspace.
    2. Plugin-specific API Manifest: When using --type apimanifest, a manifest named {plugin-name}-apimanifest.json is generated and saved in the specified output directory.

    If you change the OpenAPI document location or other plugin properties in workspace.json, a new hash (composed of the Kiota version, OpenAPI location, and manifest properties) is generated, triggering an update to these manifests.

  12. Search for APIs using the Kiota CLI

    main

    Use the kiota search command to find APIs and their descriptions from various registries.

    If your search term is an exact match for a result's key, Kiota will display a detailed view including the service URL and the OpenAPI document location. Otherwise, it returns a list of matching APIs, titles, descriptions, and available versions.