Enable linting and analysis for API governance in your API center

This article shows how to enable linting to analyze API definitions in your organization's API center for conformance with your organizations's API style rules. Linting generates an analysis report that you can access in your API center. Use API linting and analysis to detect common errors and inconsistencies in your API definitions.

Scenario overview

In this scenario, you analyze API definitions in your API center by using the Spectral open source linting engine. An Azure Functions app runs the linting engine in response to events in your API center. Spectral checks that the APIs defined in a JSON or YAML specification document conform to the rules in a customizable API style guide. A report of API compliance is generated that you can view in your API center.

The following diagram shows the steps to enable linting and analysis in your API center.

1. Deploy an Azure Functions app that runs the Spectral linting engine on an API definition.

2. Configure an event subscription in an Azure API center to trigger the function app.

3. An event is triggered by adding or replacing an API definition in the API center.

4. On receiving the event, the function app invokes the Spectral linting engine.

5. The linting engine checks that the APIs defined in the definition conform to the organization's API style guide and generates a report.

6. View the analysis report in the API center.

Options to deploy the linting engine and event subscription

This article provides two options to deploy the linting engine and event subscription in your API center:

• Automated deployment - Use the Azure developer CLI (azd) for one-step deployment of linting infrastructure. This option is recommended for a streamlined deployment process.

• Manual deployment - Follow step-by-step guidance to deploy the Azure Functions app and configure the event subscription. This option is recommended if you prefer to deploy and manage the resources manually.

Limitations

• Linting currently supports only JSON or YAML specification files, such as OpenAPI or AsyncAPI specification documents.
• By default, the linting engine uses the built-in spectral:oas ruleset. To extend the ruleset or create custom API style guides, see the Spectral GitHub repo.
• The Azure function app that invokes linting is charged separately, and you manage and maintain it.

Prerequisites

• An API center in your Azure subscription. If you haven't created one already, see Quickstart: Create your API center.

• The Event Grid resource provider registered in your subscription. If you need to register the Event Grid resource provider, see Subscribe to events published by a partner with Azure Event Grid.

• For Azure CLI:

  • Use the Bash environment in Azure Cloud Shell. For more information, see Quickstart for Bash in Azure Cloud Shell.

    

  • If you prefer to run CLI reference commands locally, install the Azure CLI. If you're running on Windows or macOS, consider running Azure CLI in a Docker container. For more information, see How to run the Azure CLI in a Docker container.

    • If you're using a local installation, sign in to the Azure CLI by using the az login command. To finish the authentication process, follow the steps displayed in your terminal. For other sign-in options, see Sign in with the Azure CLI.

    • When you're prompted, install the Azure CLI extension on first use. For more information about extensions, see Use extensions with the Azure CLI.

    • Run az version to find the version and dependent libraries that are installed. To upgrade to the latest version, run az upgrade.

  Note

  az apic commands require the apic-extension Azure CLI extension. If you haven't used az apic commands, the extension is installed dynamically when you run your first az apic command. Learn more about Azure CLI extensions.

  Note

  Azure CLI command examples in this article can run in PowerShell or a bash shell. Where needed because of different variable syntax, separate command examples are provided for the two shells.

azd deployment of Azure Functions app and event subscription

This section provides automated steps using the Azure Developer CLI to configure the Azure Functions app and event subscription that enable linting and analysis in your API center. You can also configure the resources manually.

Other prerequisites for this option

• Azure Developer CLI (azd)

Run the sample using azd

1. Clone the GitHub repository and open it in Visual Studio Code.

2. Change directory to the APICenter-Analyzer folder in the repository.

3. In the resources/rulesets folder, you can find an oas.yaml file. This file reflects your current API style guide and can be modified based on your organizational needs and requirements.

4. Authenticate with the Azure Developer CLI and the Azure CLI using the following commands:

   azd auth login
   
   az login
   

5. Run the following command to deploy the linting infrastructure to your Azure subscription.

   azd up
   

6. Follow the prompts to provide the required deployment information and settings, such as the environment name and API center name. For details, see Running the sample using the Azure Developer CLI (azd).

   Note

   The deployment might take a few minutes.

7. After the deployment is complete, navigate to your API center in the Azure portal. In the left menu, select Events > Event subscriptions to view the event subscription that was created.

You can now upload an API definition file to your API center to trigger the event subscription and run the linting engine.

Manual steps to configure Azure Functions app and event subscription

This section provides the manual deployment steps to configure the Azure Functions app and event subscription to enable linting and analysis in your API center. You can also use the Azure Developer CLI for automated deployment.

Other prerequisites for this option

• Visual Studio Code with the Azure Functions extension v1.10.4 or later.

Step 1. Deploy your Azure Functions app

To deploy the Azure Functions app that runs the linting function on API definitions:

1. Clone the GitHub repository and open it in Visual Studio Code.

2. In the resources/rulesets folder, you can find an oas.yaml file. This file reflects your current API style guide and can be modified based on your organizational needs and requirements.

3. Optionally, run the function app locally to test it. For details, see the README file in the repository.

4. Deploy the function app to Azure. For steps, see Quickstart: Create a function in Azure with TypeScript using Visual Studio Code.

   Note

   Deploying the function app might take a few minutes.

5. Sign in to the Azure portal, and go to the function app.

6. On the Overview page, check the following details:

   • Confirm that the Status of the function app is Running.
   • Under Functions, confirm that the Status of the apicenter-analyzer function is Enabled.

   

Step 2. Configure managed identity in your function app

To enable the function app to access the API center, configure a managed identity for the function app. The following steps show how to enable and configure a system-assigned managed identity for the function app using the Azure portal or the Azure CLI.

Portal

1. In the Azure portal, navigate to your function app and select Identity under the Settings section.
2. On the System assigned tab, set the Status to On and then select Save.

Now that the managed identity is enabled, assign it the Azure API Center Compliance Manager role to access the API center.

1. In the Azure portal, navigate to your API center and select Access control (IAM).
2. Select + Add > Add role assignment.
3. Select Job function roles and then select Azure API Center Compliance Manager. Select Next.
4. On the Members page, in Assign access to, select Managed identity > + Select members.
5. On the Select managed identities page, search for and select the managed identity of the function app. Click Select and then Next.
6. Review the role assignment, and select Review + assign.

Azure CLI

1. Enable the system-assigned identity of the function app using the az functionapp identity assign command. Replace <function-app-name> and <resource-group-name> with your function app name and resource group name. The following command stores the principal ID of the system-assigned managed identity in the principalID variable.

   #! /bin/bash
   principalID=$(az functionapp identity assign --name <function-app-name> \
       --resource-group <resource-group-name> --identities [system] \
       --query "principalId" --output tsv)
   

   # PowerShell syntax
   $principalID=$(az functionapp identity assign --name <function-app-name> `
       --resource-group <resource-group-name> --identities [system] `
       --query "principalId" --output tsv)
   

2. Get the resource ID of your API center. Substitute <apic-name> and <resource-group-name> with your API center name and resource group name.

   #! /bin/bash
   apicID=$(az apic service show --name <apic-name> --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

   # PowerShell syntax
   $apicID=$(az apic service show --name <apic-name> --resource-group <resource-group-name> `
       --query "id" --output tsv)
   

3. Assign the function app's managed identity the Azure API Center Compliance Manager role in the API center using the az role assignment create command.

   #! /bin/bash
   az role assignment create \
       --role "Azure API Center Compliance Manager" \
       --assignee-object-id $principalID \
       --assignee-principal-type ServicePrincipal \
       --scope $apicID 
   

   # PowerShell syntax
   az role assignment create `
       --role "Azure API Center Compliance Manager" `
       --assignee-object-id $principalID `
       --assignee-principal-type ServicePrincipal `
       --scope $apicID 
   

Step 3. Configure event subscription in your API center

Now create an event subscription in your API center to trigger the function app when an API definition file is uploaded or updated. The following steps show how to create the event subscription using the Azure portal or the Azure CLI.

Portal

1. In the Azure portal, navigate to your API center and select Events.

2. On the Get started tab, select Azure Function.

3. On the Create Event Subscription page, do the following:

   1. Enter a descriptive Name for the event subscription, and select Event Grid Schema.

   2. In Topic details, enter a System topic name of your choice.

   3. In Event Types, select the following events:

      • API definition added
      • API definition updated

   4. In Endpoint Details, select Azure Function > Configure an endpoint.

   5. On the Select Azure Function page, select the function app and the apicenter-linter function that you configured. Click Confirm selection.

   6. Select Create.

      

4. Select the Event subscriptions tab and select Refresh. Confirm that the Provisioning state of the event subscription is Succeeded.

   

Azure CLI

1. Get the resource ID of your API center. Substitute <apic-name> and <resource-group-name> with your API center name and resource group name.

   #! /bin/bash
   apicID=$(az apic service show --name <apic-name> --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

   # PowerShell syntax
   $apicID=$(az apic service show --name <apic-name> --resource-group <resource-group-name> `
       --query "id" --output tsv)
   

2. Get the resource ID of the function in the function app. In this example, the function name is apicenter-analyzer. Substitute <function-app-name> and <resource-group-name> with your function app name and resource group name.

   #! /bin/bash
   functionID=$(az functionapp function show --name <function-app-name> \
       --function-name apicenter-analyzer --resource-group <resource-group-name> \
       --query "id" --output tsv)
   

   # PowerShell syntax
   $functionID=$(az functionapp function show --name <function-app-name> `
       --function-name apicenter-analyzer --resource-group <resource-group-name> `
       --query "id" --output tsv)
   

3. Create an event subscription using the az eventgrid event-subscription create command. The subscription that's created includes events for adding or updating API definitions.

   #! /bin/bash
   az eventgrid event-subscription create --name MyEventSubscription \
       --source-resource-id "$apicID" --endpoint "$functionID" \
       --endpoint-type azurefunction --included-event-types \
       Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated
   

   # PowerShell syntax
   az eventgrid event-subscription create --name MyEventSubscription `
       --source-resource-id "$apicID" --endpoint "$functionID" `
       --endpoint-type azurefunction --included-event-types `
       Microsoft.ApiCenter.ApiDefinitionAdded Microsoft.ApiCenter.ApiDefinitionUpdated
   

   The command output shows details of the event subscription. You can also get details using the az eventgrid event-subscription show command. For example:

   az eventgrid event-subscription show --name MyEventSubscription --source-resource-id "$apicID"
   

Note

It might take a short time for the event subscription to propagate to the function app.

Trigger event in your API center

To test the event subscription, try uploading or updating an API definition file associated with an API version in your API center. For example, upload an OpenAPI or AsyncAPI document. After the event subscription is triggered, the function app invokes the API linting engine to analyze the API definition.

• For detailed steps to add an API, API version, and API definition to your API center, see Tutorial: Register APIs in your API center.
• To create an API by uploading an API definition file using the Azure CLI, see Register API from a specification file.

To confirm that the event subscription was triggered:

1. Navigate to your API center, and select Events in the left menu.

2. Select the Event Subscriptions tab and select the event subscription for your function app.

3. Review the metrics to confirm that the event subscription was triggered and that linting was invoked successfully.

   

   Note

   It might take a few minutes for the metrics to appear.

After analyzing the API definition, the linting engine generates a report based on the configured API style guide.

View API analysis reports

You can view the analysis report for your API definition in the Azure portal. After an API definition is analyzed, the report lists errors, warnings, and information based on the configured API style guide.

In the portal, you can also view a summary of analysis reports for all API definitions in your API center.

Analysis report for an API definition

To view the analysis report for an API definition in your API center:

1. In the portal, navigate to the API version in your API center where you added or updated an API definition.
2. In the left menu, under Details, select Definitions.
3. Select the API definition that you uploaded or updated.
4. Select the Analysis tab.

The API Analysis Report opens, and it displays the API definition and errors, warnings, and information based on the configured API style guide. The following screenshot shows an example of an API analysis report.

API analysis summary

To view a summary of analysis reports for all API definitions in your API center:

1. In the portal, navigate to your API center.

2. In the left-hand menu, under Governance, select API Analysis. The summary appears.

   

Related content

Learn more about Event Grid:

• System topics in Azure Event Grid
• Event Grid push delivery - concepts
• Event Grid schema for Azure API Center