Azure API Management 101

Summary

This is a note that walks you through the first step of Azure Azure API Mamanagement. Here is the code sample of Azure Pipelines Yaml and .NET6.

Architecture

Step by Step

Deploy

Setup BASE_NAME and ENVIRONMENT_SYMBOL in variables-template.yml
Run Azure pipelines with iac-pipeline-apim.yml
Run Azure pipelines with dotnet-pipeline-travelapi.yml

Extract swagger.json

OpenAPI format in API Management requires [swagger.json] file. You can extract the file by running the app TravelApi locally. The file location will be like https://localhost:7228/swagger/v1/swagger.json

swagger.json example

{
  "openapi": "3.0.1",
  "info": {
    "title": "TravelApi",
    "version": "1.0"
  },
  "paths": {
    "/TravelPlan": {
      "get": {
        "tags": [
          "TravelPlan"
        ],
        "summary": "Get a list of destinations",
        "description": "Sample request:\r\n            \r\n    GET /travelplan",
        "responses": {
          "400": {
            "description": "Bad Request"
          },
          "401": {
            "description": "Unauthorized"
          },
          "500": {
            "description": "Server Error"
          },
          "503": {
            "description": "Server Error"
          },
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Destination"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Destination": {
        "type": "object",
        "properties": {
          "country": {
            "type": "string",
            "nullable": true
          },
          "city": {
            "type": "string",
            "nullable": true
          },
          "food": {
            "type": "string",
            "nullable": true
          },
          "sightSeeing": {
            "type": "string",
            "nullable": true
          }
        },
        "additionalProperties": false
      }
    }
  }
}

swagger.json when running locally

Import the API

The code sample already includes a TravelApi api in ARM template azuredeploy-apim.json. It does not have the content of API, and you need to import and append swagger.json to it.

azuredeploy-apim.json

{
  "type": "Microsoft.ApiManagement/service/apis",
  "apiVersion": "2021-08-01",
  "name": "[concat(variables('apim_name'), '/travelapi')]",
  "dependsOn": [
    "[resourceId('Microsoft.ApiManagement/service', variables('apim_name'))]"
  ],
  "properties": {
    "displayName": "TravelApi",
    "subscriptionRequired": true,
    "serviceUrl": "[variables('apim_service_url')]",
    "protocols": [
      "https"
    ],
    "path": ""
  }
}

Go to Azure Portal and the deployed Azure API Management. You will see TravelApi is already set by ARM template. You are going to add swagger.json here. APIs --> TravelApi --> Import

Select OpenAPI

Select swagger.json extracted in the previous step. Select Append and Postfix, and Import.

Test the API (Azure Portal)

Go to API Management --> APIs --> TravelApi --> Test --> GET /TravelPlan, and Send. You will see the successful response from the deployed App Service.

Get subscription key

In order to test the API from your local machine, you need to get a subscription key to access the API.

Go to API Management --> Subscriptions --> Build-in all-access subscription, and then keep Primary Key for later usage.

Test the API (Local)

Send HTTP request from the terminal like below.

Bash example

curl -H "Ocp-Apim-Subscription-Key: {Primary Key}" https://{API Management name}.azure-api.net/travelplan

Example response

[
  {
    "country": "France",
    "city": "Paris",
    "food": "Wine",
    "sightSeeing": "Eiffel Tower"
  },
  {
    "country": "Japan",
    "city": "Tokyo",
    "food": "Ramen",
    "sightSeeing": "Skytree"
  }
]

API Management purge

According to the Microsoft official document as of January 2022, an API Management instance is soft-deleted (Azure Resource Manager API 2020-06-01-preview or later). Retention interval of soft-deleted instance is 48 hours. You can also hard-delete the soft-deleted instance by using the REST API.

Azure CLI Powershell sample

az rest --method delete --header "Accept=application/json" `
-u 'https://management.azure.com/subscriptions/{Azure Subscription ID}/providers/Microsoft.ApiManagement/locations/{Location}/deletedservices/{API Management name}?api-version=2021-08-01'