Overview

A robust extension that automates API deployments to Azure API Management (APIM). This task streamlines your CI/CD pipeline by providing seamless API lifecycle management:

API: Import or update existing APIs from OpenAPI/Swagger specifications.
API Versioning: Manage API versions using path, header, or query-based versioning.
API Level Policies: Apply custom policies at API scope for security, transformation, and rate limiting.
Operation Level Policies: Apply policies at the operation level for fine-grained control.
API Subscription: Enable subscription requirements and customize subscription key header/query parameter names.
Product Association: Associate APIs with existing APIM products for access control (safely appends without affecting existing configurations).
Self-hosted Gateway: Deploy API to self-hosted gateways.

This extension seamlessly integrates with both Azure Pipelines (YAML) and Classic Release pipelines. Supports all APIM SKUs with comprehensive error handling, and real-time operational insights.

Execution Flow

API Import

Click to see detailed execution flow

Specification Discovery

Fetches OpenAPI/Swagger from URL or file
Validates specification structure and content
Extracts metadata like display name and server info

API Detection & Update

Checks for existing API by path
Updates if found, preserving existing settings
Creates new if not found.

API Versioning Configuration

Configures API versioning scheme (Path, Header, Query)
Converts existing non-versioned API as Orginal and creates versioned based on the schema.
Sets up version identifiers

Subscription Configuration

Enables Require subscription option
Configures custom subscriptionHeader and Query parameter

Product Association

Adds to the existing product(s) (if specified)

Policy Configuration

Maintains existing policy base sections
Applies API-level policies from file or inline
Applies operation-level policies from folder

Gateway Publishing

Configures API to be available via self-hosted gateways

Deployment Summary ✨

Shows API operations table
Shows product associations status (if specified)
Shows Policy apply status (if specified)
Displays gateway and developer portal endpoints

Prerequisites

Required Components

Azure DevOps Services
An Azure subscription
Azure API Management instance
Service connection with permissions to manage APIM

Authentication Options

Microsoft-hosted agents: Consider using Workload Identity Federation
Self-hosted agents: Consider using Managed Identity
Other scenarios: Service Principal authentication

Task Configuration

Input Name	Required	Default Value	Description
Connection Settings
`ConnectedServiceNameARM`	Yes		Service connection name
`resourceGroupName`	Yes		Resource group containing APIM instance
`serviceName`	Yes		APIM service name
API Specification
`sourceType`	Yes	`url`	Source type ('url' or 'file')
`apiPath`	Yes		API URL suffix (must be unique within the API Management instance)
`specificationUrl`	Yes*		URL pointing to API specification (*required if sourceType = 'url')
`urlFormat`	Yes*	`openapi+json-link`	Format for URL specification: 'swagger-link-json', 'openapi-link', 'openapi+json-link' (*required if sourceType = 'url')
`specificationPath`	Yes*		Path to local API specification file (*required if sourceType = 'file')
`fileFormat`	Yes*	`openapi+json`	Format for file specification: 'swagger-json', 'openapi', 'openapi+json' (*required if sourceType = 'file')
API Configuration
`urlScheme`	No	`https`	URL schemes API supports: 'http', 'https', 'both'
`requireSubscription`	No	`true`	Whether API requires subscription key
`subscriptionKeyHeader`	No	`Ocp-Apim-Subscription-Key`	Custom header name for subscription key
`subscriptionKeyQuery`	No	`subscription-key`	Custom query param name for subscription key
`useCustomServiceUrl`	No	`false`	Whether to use a custom backend URL
`customServiceUrl`	Yes*		Custom backend service URL (*required if useCustomServiceUrl = true)
API Versioning
`enableVersioning`	No	`false`	Create/update a versioned API
`versioningScheme`	Yes*	`Segment`	Versioning scheme: 'Segment' (path), 'Header', 'Query' (*required if enableVersioning = true)
`versionIdentifier`	Yes*	`v1`	Version number (v1, 1.0.0, etc.) (*required if enableVersioning = true)
`versionHeaderName`	Yes*		Header name for version (*required if versioningScheme = 'Header')
`versionQueryName`	Yes*		Query param name for version (*required if versioningScheme = 'Query')
Product Association
`addToProducts`	No	`false`	Associate API with products
`products`	Yes*	`starter`	Comma-separated product names (*required if addToProducts = true)
Gateway Configuration
`enableSelfHostedGateway`	No	`false`	Use self-hosted gateway
`gatewayName`	Yes*		Name of self-hosted gateway (*required if enableSelfHostedGateway = true)
Policy Configuration
`applyApiPolicy`	No	`false`	Apply custom policy at API scope
`apiPolicySource`	Yes*	`inline`	Policy source type: 'inline' or 'file' (*required if applyApiPolicy = true)
`apiPolicyContent`	Yes*		XML policy content (*required if apiPolicySource = 'inline')
`apiPolicyFilePath`	Yes*		Path to policy XML file (*required if apiPolicySource = 'file')
`apiOperationsPolicy`	No	`false`	Apply policies at operation level
`operationPolicyFolderPath`	Yes*		Path to folder containing operation policy XML files (*required if apiOperationsPolicy = true)

* Required based on condition

Examples

Import from URL

steps:
- task: AzureAPIMImport@1
  displayName: 'Import API from URL'
  inputs:
    ConnectedServiceNameARM: '$(azureSubscription)'
    resourceGroupName: '$(resourceGroup)'
    serviceName: '$(apimService)'
    sourceType: 'url'
    specificationUrl: 'https://petstore.swagger.io/v2/swagger.json'
    apiPath: 'petstore'

Import from File

steps:
- task: AzureAPIMImport@1
  displayName: 'Import API from File'
  inputs:
    ConnectedServiceNameARM: '$(azureSubscription)'
    resourceGroupName: '$(resourceGroup)'
    serviceName: '$(apimService)'
    sourceType: 'file'
    specificationPath: '$(System.DefaultWorkingDirectory)/specs/api.json'
    fileFormat: 'openapi+json'
    apiPath: 'customer-api'

Note: These are the minimum required parameters for API import/update. Additional parameters can be added based on your needs.

Advanced API Import with Versioning and Policy

steps:
- task: AzureAPIMImport@1
  displayName: 'Import Versioned API with Policy'
  inputs:
    # Azure Connection Settings
    ConnectedServiceNameARM: '$(azureSubscription)'
    resourceGroupName: '$(resourceGroup)'
    serviceName: '$(apimService)'

    # API Specification Settings
    sourceType: 'file'
    specificationPath: '$(System.DefaultWorkingDirectory)/specs/api.json'
    fileFormat: 'openapi+json'
    apiPath: 'customer-api'
    urlScheme: 'https'

    # API Configuration
    requireSubscription: true
    subscriptionKeyHeader: 'Ocp-Apim-Subscription-Key'
    useCustomServiceUrl: true
    customServiceUrl: 'https://custom-backend.example.com'

    # Versioning Settings
    enableVersioning: true
    versioningScheme: 'Header'
    versionHeaderName: 'api-version'
    versionIdentifier: 'v1'

    # Product Association
    addToProducts: true
    products: |
      'Starter,Unlimited'

    # Policy Configuration
    applyApiPolicy: true
    apiPolicySource: 'inline'
    apiPolicyContent: |
      <policies>
          <inbound>
              <base />
              <rate-limit calls="5" renewal-period="60" />
          </inbound>
          <backend>
              <base />
          </backend>
          <outbound>
              <base />
          </outbound>
          <on-error>
              <base />
          </on-error>
      </policies>

API import + Self-hosted Gateway API Deployment with Custom Policy

steps:
- task: AzureAPIMImport@1
  displayName: 'Deploy API to Self-hosted Gateway'
  inputs:
    # Azure Connection Settings
    ConnectedServiceNameARM: '$(azureSubscription)'
    resourceGroupName: '$(resourceGroup)'
    serviceName: '$(apimService)'

    # API Specification Settings
    sourceType: 'url'
    specificationUrl: 'https://api.example.com/openapi.json'
    urlFormat: 'openapi+json-link'
    apiPath: 'customer-api'

    # Gateway Configuration
    enableSelfHostedGateway: true
    gatewayName: 'k8s-gateway'

    # Policy Configuration
    applyApiPolicy: true
    apiPolicySource: 'file'
    apiPolicyFilePath: '$(System.DefaultWorkingDirectory)/policies/api-policy.xml'

API import with Operation-level Policies

steps:
- task: AzureAPIMImport@1
  displayName: 'Import API with Operation Policies'
  inputs:
    # Azure Connection Settings
    ConnectedServiceNameARM: '$(azureSubscription)'
    resourceGroupName: '$(resourceGroup)'
    serviceName: '$(apimService)'

    # API Specification Settings
    sourceType: 'file'
    specificationPath: '$(System.DefaultWorkingDirectory)/specs/api.json'
    fileFormat: 'openapi+json'
    apiPath: 'customer-api'

    # API-level Policy
    applyApiPolicy: true
    apiPolicySource: 'file'
    apiPolicyFilePath: '$(System.DefaultWorkingDirectory)/policies/api-policy.xml'
    
    # Operation-level Policies
    apiOperationsPolicy: true
    operationPolicyFolderPath: '$(System.DefaultWorkingDirectory)/policies/operations'