kiota-samples/sample-api/api

Kiota ToDoItem Sample API

This sample implements a basic OData Web API. The OpenAPI description generated by the sample can be used with Kiota to generate client-side SDKs.

Prerequisites

• .NET SDK version 7+
• An Azure account with an active subscription. Create an Azure account for free or join the Microsoft 365 Developer Program to get a free instant sandbox for testing.
• The Azure account must have permission to manage applications in Azure Active Directory (Azure AD). Any of the following Azure AD roles include the required permissions:
  • Application administrator
  • Application developer
  • Cloud application administrator
  • Global administrator

Configure the sample

The sample uses Azure AD to protect the Web API. You'll need to register an application in Azure AD and add the app registration to the sample. You can install the Microsoft Graph PowerShell SDK and use the included PowerShell script to automate the process, or register the app manually.

Use PowerShell

Note: The PowerShell script requires an account with the Application administrator, Cloud application administrator, or Global administrator role. If your account has the Application developer role, you can register manually.

Open PowerShell in the root of this project and run the following command.

.\RegisterAPI.ps1

This will open a browser window to the Microsoft identity platform's sign-in page. Sign in with your Azure account, review the requested permissions, and consent to the application. This creates an app registration named Kiota ToDoItem Sample API and save the needed configuration in ./src/appsettings.Development.json. It also outputs the API scope client application will need to access the API.

The script also accepts optional parameters to change how it behaves.

• -AppName <string>: Set the name of the app registration
• -TenantId <string>: Specify the tenant ID of the Azure subscription to create the app registration in.
• -StayConnected: The script will leave the Microsoft Graph PowerShell SDK's session open rather than disconnect when it is finished.

Register manually

1. Open a browser and navigate to the Azure Active Directory admin center. Login with your Azure account.

2. Select Azure Active Directory in the left-hand navigation, then select App registrations under Manage.

3. Select New registration. On the Register an application page, set the values as follows.

   • Set Name to Kiota ToDoItem Sample API.
   • Set Supported account types to Accounts in this organizational directory only.
   • Leave Redirect URI blank.

4. Select Register. On the Kiota ToDoItem Sample API page, copy the values of the Application (client) ID and **Directory (tenant) ID and save them, you will need to add them to the sample once you are done configuring the app registration.

5. Select Expose an API under Manage, then choose Add a scope.

6. Accept the default Application ID URI and choose Save and continue.

7. Fill in the Add a scope form as follows:

   • Scope name: ToDoItem.ReadWrite
   • Who can consent?: Admins and users
   • Admin consent display name: Full access to users' ToDoItems
   • Admin consent description: Allows the app to read and write users' ToDoItems
   • User consent display name: Full access to your ToDoItems
   • User consent description: Allows the app to read and write your ToDoItems
   • State: Enabled

8. Select Add scope.

9. Copy the new scope, you'll need it to configure client applications.

10. Create a new file in the ./src directory named appsettings.Development.json and add the following contents. Replace YOUR_CLIENT_ID with the client ID from your app registration, and replace YOUR_TENANT_ID with your tenant ID.

    {
      "AzureAd": {
        "ClientId": "YOUR_CLIENT_ID",
        "TenantId": "YOUR_TENANT_ID"
      }
    }
    

Run the sample

Start the sample with the dotnet run command in the ./src directory. Alternatively, you can open this project folder with Visual Studio Code or open kiota-sample-api.sln with Visual Studio and debug the code by pressing F5.

Once the application has started, open a browser and navigate to https://localhost:7206/openapi/openapi.yaml to view the OpenAPI description for the sample API.

Calling the API

To call this API, you'll need a client capable of getting access tokens from the Microsoft identity platform and making HTTP requests. You can get started writing your own client by generating an SDK for the sample API with Kiota.

With the sample running, you can use https://localhost:7206/openapi/openapi.yaml as the value for the --openapi parameter to generate an SDK.

kiota --openapi https://localhost:7206/openapi/openapi.yaml ...

See Using the Kiota tool for a full listing of available parameters.