ZZZ ‐ [Archived] ‐ Connect to existing APIs

Connect to existing APIs

This feature is currently under active development. Report any issues to us here.

When building a Teams application often you will want to access existing APIs - these might be APIs developed by your organization or even 3rd party APIs. If you do not have language appropriate SDKs to access these APIs, Teams Toolkit helps you bootstrap sample code to access these APIs.

In this tutorial, you will:

• Use Teams Toolkit to connect to an existing API
• Understand the changes to your project when you connect to an existing API
• Invoke the API in the Teams Toolkit local environment
• Add configuration to access the API when you deploy your application to Azure
• Use a custom authentication provider
• Obtain API permissions with Microsoft Entra protected API request

How to use this feature

When you use Teams Toolkit to connect to an existing API, Teams Toolkit will:

• Generate sample code under ./bot or ./api folder.
• Add a reference to the @microsoft/teamsfx package to package.json.
• Add application settings for your API in .env.teamsfx.local, which configures local debugging.

To add an API connection:

In Visual Studio Code

1. Open a TeamsFx project
2. From the Teams Toolkit side bar select Add features or open the Visual Studio Code Command Palette and select Teams: Add features:

2. Select API Connection:

3. Input endpoint for your API. The endpoint should be a valid http(s) url. It will be added to your project's local application settings and it is the base url for API requests.

4. Choose which component will access the API.

5. Input an alias for your API. This alias is used to generate the application settings name for your API, and it will be added to your project's local application settings.

6. Select how you want to authenticate the API requests. We will generate appropriate sample code and add corresponding local application settings based on your selection.

7. There will be some additional configuration required based on the authentication type selected.

In TeamsFx CLI

The base command of this feature is teamsfx add api-connection [authentication type]. Here is the list of available authentication type and corresponding sample command. You can use teamsfx add api-connection [authentication type] -h to get help document.

Authentication type	Sample command
Basic	teamsfx add api-connection basic --endpoint https://example.com --component bot --alias example --user-name exampleuser --interactive false
API Key	teamsfx add api-connection apikey --endpoint https://example.com --component bot --alias example --key-location header --key-name example-key-name --interactive false
Microsoft Entra	teamsfx add api-connection aad --endpoint https://example.com --component bot --alias example --app-type custom --tenant-id your_tenant_id --app-id your_app_id --interactive false
Certificate	teamsfx add api-connection cert --endpoint https://example.com --component bot --alias example --interactive false
Custom	teamsfx add api-connection custom --endpoint https://example.com --component bot --alias example --interactive false

back to top

Understanding the updates to your project

Teams Toolkit will make following changes to bot or api folder based on your selections:

1. Generate {your_api_alias}.js/ts. The file initializes an API client for your API and exports the API client.
2. Add @microsoft/teamsfx package to package.json. The package provides support for common API authentication methods.
3. Add environment variables to .env.teamsfx.local. These are the configuration for the selected authentication type. The generated code will read values from these environment variables.

back to top

Testing your API connection in the Teams Toolkit local environment

After adding an API connection:

1. Run npm install

You need to run npm install under bot or api folder to install the added packages.

2. Add your API credentials to the local application settings

Teams Toolkit does not ask for credentials but it will leave placeholders in the local application settings file. Substitute these placeholders with the appropriate credentials to access the API. The local application settings file is the .env.teamsfx.local file in the bot or api folder.

3. Use the API client to make API requests

Import the API client from the source code that needs access to the API:

import { yourApiClient } from '{relative path to the generated file}'

4. Make http(s) requests to target API (with Axios)

The generated API client is an Axios API client. Use the Axios client to make requests to the API.

Axios is a popular nodejs package for making http(s) requests. You can visit Axios documentation for more information.

back to top

Deploy your application to Azure

To deploy your application to Azure, you will need to add the authentication configuration to the application settings for the appropriate environment. For example, your API might have different credentials for dev and prod. You can configure Teams Toolkit appropriately based on your environment needs.

Teams Toolkit only configures your local environment. The bootstrapped sample code contains comments that tell you what app settings you need to configure. This document contains more information on adding application settings.

back to top

Advanced scenarios

Custom authentication provider

Besides the authentication provider included in @microsoft/teamsfx package, you can also implement your customized authentication provider that implements AuthProvider interface and use it in createApiClient(..) function:

import { AuthProvider } from '@microsoft/teamsfx'

class CustomAuthProvider implements AuthProvider {
    constructor() {
        // You can add necessary parameters for your customized logic in constructor
    }

    AddAuthenticationInfo: (config: AxiosRequestConfig) => Promise<AxiosRequestConfig> = async (
        config
    ) => {
        /*
        * The config parameter contains all the request information and can be updated to include extra authentication info.
        * Refer https://axios-http.com/docs/req_config for detailed document for the config object.
        * 
        * Add your customized logic that returns updated config
        */
    };
}

back to top

Connecting to APIs that require Microsoft Entra permissions

Some services are authenticated by Microsoft Entra. To access these services, there are two common ways to configure the API permissions:

• Use Access Control Lists (ACLs)
• Use Microsoft Entra application permissions

Obtaining a token with the right resource scopes for your API depends on the implementation of the API. Here are the steps to access these APIs:

When using Microsoft Entra application permissions

1. Open templates/appPackage/aad.template.json and add the following to requiredResourceAccess property:

    {
        "resourceAppId": "The Microsoft Entra App Id for the service providing the API you are connecting to",
        "resourceAccess": [
            {
                "id": "Target API's application permission Id",
                "type": "Role"
            }
        ]
    }
   

2. Start local debug or provision an cloud environment for your project. This will create an Microsoft Entra Application Registration your Teams application.
3. Open .fx/states/state.{env}.json and note the value of clientId under fx-resource-aad-app-for-teams property. This is your Teams application client id.
4. Follow this document to gain admin consent for the required application permission. You will need your application client id.

When using Access Control Lists (ACsL)

1. Start local debug or provision an cloud environment for your project. This will create an Microsoft Entra Application Registration your Teams application.
2. Open .fx/states/state.{env}.json and note the value of clientId under fx-resource-aad-app-for-teams property.
3. Provide the client id to your API provider to configure ACLs on the API service.

back to top