Part 3: Example third-party API implementation

Previous part: Authentication requirements

In our example scenario, the main app's public endpoint uses a third-party API that's secured by an access key. This section shows an implementation of the third-party API using Azure Functions, but the API could be implemented in other ways and deployed to a different cloud server or web host. The only important aspect is that client requests to the protected endpoint must include the access key. Any app that invokes this API must securely manage that key.

For demonstration purposes, this API is deployed to the endpoint, https://msdocs-example-api.azurewebsites.net/api/RandomNumber. To call the API, however, you must provide the access key d0c5atM1cr0s0ft either in a ?code= URL parameter or in an 'x-functions-key' property of the HTTP header. For example, after you've deployed the app and API, try this URL in a browser or curl: https://msdocs-example-api.azurewebsites.net/api/RandomNumber?code=d0c5atM1cr0s0ft.

If the access key is valid, the endpoint returns a JSON response that contains a single property, "value", the value of which is a number between 1 and 999, such as {"value": 959}.

The endpoint is implemented in Python and deployed to Azure Functions. The code is as follows:

import logging
import random
import json

import azure.functions as func


def main(req: func.HttpRequest) -> func.HttpResponse:
    logging.info('RandomNumber invoked via HTTP trigger.')

    random_value = random.randint(1, 1000)
    dict = { "value" : random_value }
    return func.HttpResponse(json.dumps(dict))

In the sample repository, this code is found under third_party_api/RandomNumber/__init__.py. The folder, RandomNumber, provides the name of the function and __init__.py contains the code. Another file in the folder, function.json, describes when the function is triggered. Other files in the third_party_api parent folder provide details for the Azure Function app that hosts the function itself.

To deploy the code, the sample's provisioning script performs the following steps:

1. Create a backing storage account for Azure Functions with the Azure CLI command, az storage account create.

2. Create an Azure Functions app with the Azure CLI command, az function app create.

3. After waiting 60 seconds for the host to be fully provisioned, deploy the code using the Azure Functions Core Tools command, func azure functionapp publish.

4. Assign the access key, d0c5atM1cr0s0ft, to the function. (See Securing Azure Functions for a background on function keys.)

   In the provisioning script, this step is accomplished using the az functionapp function keys set Azure CLI command.

   Comments are included to show how to do this step through a REST API call to the Functions Key Management API if desired. To call that REST API, another REST API call must be done first to retrieve the Function app's master key.

   You can also assign access keys through the Azure portal. On the page for the Functions app, select Functions, then select the specific function to secure (which is named RandomNumber in this example). On the function's page, select Function Keys to open the page where you can create and manage these keys.

Part 4 - Main app implementation >>>