This section describes the extractor component which forms the core tool used to extract artifacts from Azure APIM using APIOps.


The extractor generates APIOps artifacts from an existing APIM instance. These artifacts can then be used as the source of truth for your APIM environment; make changes to them and have a CI/CD process update your Azure environment (with the publisher tool, for instance).


The tool expects certain configuration parameters. These can be passed as environment variables, command line arguments, etc. It will look for variables using the Host.CreateDefaultBuilder(arguments) settings. Here are the expected parameters:

Variable Purpose
AZURE_SUBSCRIPTION_ID Subscription ID of the APIM instance to be extracted
AZURE_RESOURCE_GROUP_NAME Resource group name of the APIM instance to be extracted
AZURE_BEARER_TOKEN Token for authentication to Azure. If this is not specified, the tool authenticate with the DefaultAzureCredential.
API_MANAGEMENT_SERVICE_NAME Name of the APIM instance to be extracted
API_MANAGEMENT_SERVICE_OUTPUT_FOLDER_PATH Folder where the APIM artifacts will be saved
API_SPECIFICATION_FORMAT OpenAPI specification format. Valid options are JSON or YAML. If the variable is missing or invalid, YAML will be used by default
ARM_API_VERSION Azure ARM API version that will be used. This is a optional parameter and will default to 2022-04-01-preview if not specified. Other versions can be found here APIM Rest API Reference - Overview Docs.
CONFIGURATION_YAML_PATH Path to the Yaml configuration file used to specify select apis to extract. A sample yaml extractor configuration file to signal to the extractor to extract select apis. This is an optional parameter and will only come into play if you want different teams to manage different apis. You typically will have one configuration per team. Note: You can call the file whatever you want as long as you reference the right file within your extractor pipeline.
AZURE_CLOUD_ENVIRONMENT Azure Authority Host Service url that will be used. This is a optional parameter and will default to AzurePublicCloud if not specified.
Logging__LogLevel__Default: The allowed values are either “Information”, “Debug”, or “Trace”. Table below shows the description of each logging level.

Here are the different logging levels available. By default the logging level is set to “Information”.

Log Level Description
Information Logs that track the general flow of the application. These logs should have long-term value
Debug Logs that are used for interactive investigation during development. These logs should primarily contain information useful for debugging and have no long-term value
Trace Logs that contain the most detailed messages. These messages may contain sensitive application data. These messages are disabled by default and should never be enabled in a production environment


The specification file format is controlled by the configuration variable API_SPECIFICATION_FORMAT. Here are the options:

Configuration value Action
Not specified Use OpenAPI v3 YAML
Json Use OpenAPI v3 JSON (for backward compatibility. Use OpenAPIV3Json instead )
Yaml Use OpenAPI v3 YAML (for backward compatibility. Use OpenAPIV3Yaml instead )
OpenAPIV2Json Use OpenAPI v2 JSON
OpenAPIV2Yaml Use OpenAPI v2 YAML
OpenAPIV3Json Use OpenAPI v3 JSON
OpenAPIV3Yaml Use OpenAPI v3 YAML

The configuration values are case-insensitive.

APIM doesn’t support OpenAPI v2 YAML. If you want to extract OpenAPI v2 YAML, the extractor extracts in JSON and converts to YAML. For publishing, the tool converts the YAML to JSON and pushes it.

The figures below demonstrates specifying the the openapi specification format in both Azure Devops and Github Actions.




The Azure Authority Host Service url is controlled by the configuration variable AZURE_CLOUD_ENVIRONMENT. Here are the options:

Value Url


The extractor will export the artifacts listed below.

Note that all artifacts gets exported in parallel. We use retry up to 10 times with exponential backoff in case Azure throttles the requests, but keep this in mind in case you have many APIs/operations and experience IO issues.

Type Path
APIM instance global policy ./policy.xml
Product information ./products/product_display_name/productInformation.json
Product Groups ./products/product_display_name/policy.xml
Product Groups ./products/product_display_name/groups.json. Please note that we don’t create the groups. We only associate with existing ones that would be created using IaC tool like ARM/Bicep/Terraform which is outside the scope of this tool
Gateway information ./gateways/gateway_name/gatewayInformation.json
Authorization server information ./authorizationServers/authorization_server_name/authorizationServerInformation.json
Diagnostic information ./diagnostics/diagnostic_name/diagnosticInformation.json
Logger information ./loggers/logger_name/loggerInformation.json
Non Versioned/revisioned API information ./apis/api_name/Original/1/apiInformation.json
Non Versioned/revisioned specification information ./apis/api_name/Original/1/specification.yaml
Versioned API information ./apis/api_name/Original serves as v1 in addition to folders for each version/1/apiInformation.json
Versioned specification information ./apis/api_name/Original serves as v1 in addition to folders for each version/1/specification.yaml
revisioned API information ./apis/api_name/Original\[revision number]/apiinformation.json
revisioned specification information ./apis/api_name/Original\[revision number]/specification.yaml
OpenAPI specification ./apis/api_name/specification.{yaml|json}
API policy ./apis/api_name/policy.xml
Operation policy ./apis/api_name/operations/operation_name/policy.xml
tags ./tags/tag_name
backends ./backends/backend_name

Extracting Select Artifacts

There are cases where you may want to extract select artifacts (e.g. specific apis, products, etc.) instead of extracting everything. This could be a result of having a requirement to promote specific artifacts across environments or as a result of supporting multiple teams where each team may be responsible for select artifacts. ApiOPS supports this feature and you can find the details in the “Supporting Independent API Teams” section.

Note We recommend looking into workspaces in the future which allows decentralized API development teams to manage and productize their own APIs, while a central API platform team maintains the API Management infrastructure. Each workspace contains APIs, products, subscriptions, and related entities that are accessible only to the workspace collaborators. Access is controlled through Azure role-based access control (RBAC). ApiOPS will bring support for workspaces when it becomes generally available.