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

Extractor

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).

Parameters

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

API_SPECIFICATION_FORMAT

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.

AZURE_CLOUD_ENVIRONMENT

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

Value	Url
AzurePublicCloud	https://management.azure.com/
AzureChinaCloud	https://management.chinacloudapi.cn/
AzureGermanCloud	https://management.microsoftazure.de/
AzureUSGovernment	https://management.usgovcloudapi.net/

Artifacts

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.