02 What can be managed by APIM APIOps?

Please refer to the subsections below for guidance, additional information, and possibilities. Each category represents areas in Azure API Management (APIM) that can be configured and is represented by its own subsection.

Each subsection starts with a table that shows the folder where the configuration is done, the required and optional files, along with a corresponding description.

Under each table in each section, there is a detailed description of functionality and examples with minimum configuration. Where applicable, there are also examples of configurations with all available options.

Please see the article about the artifacts folder for information about the folder where the configuration files should be stored.

APIs

Category	Path	File	Required / Optional	Description
APIs	`<artifacts folder>/apis/<API name>`	`apiInformation.json`	Required	Metadata about the API, such as display name, description, path, version set, etc.
APIs	`<artifacts folder>/apis/<API name>`	`specification.json` / `specification.yaml`	Required	OpenAPI specification in either JSON or YAML format.
APIs	`<artifacts folder>/apis/<API name>`	`policy.xml`	Optional	Policy for the API itself.

For each API, a subfolder must be created as shown in the table above, where the name of the subfolder will be the name of the API.

Although it is possible, the module isn't developed to support GraphQL, SOAP or WebSocket.

`apiInformation.json`

Example with minimum configuration

{
  "properties": {
    "displayName": "Demo Conference API",
    "description": "A sample API with information related to a technical conference.",
    "path": "conference"
  }
}

Example with all configuration

{
  "properties": {
    "displayName": "Swagger Petstore - OpenAPI 3.0",
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.",
    "apiRevision": "1",
    "path": "petstore",
    "apiVersionSet": {
      "version": "v1",
      "versionSetName": "swagger-petstore"
    },
    "subscriptionRequired": true,
    "subscriptionKeyParameterNames": {
      "header": "Ocp-Apim-Subscription-Key",
      "query": "subscription-key"
    },
    "protocols": [
      "https",
      "http"
    ],
    "serviceUrl": "https://petstore3.swagger.io/api/v3",
    "contact": {
      "name": "John Doe",
      "email": "[email protected]",
      "url": "https://petstore3.swagger.io"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
    },
    "termsOfService": "http://swagger.io/terms/",
    "tags": [
      "tag1",
      "tag2"
    ],
    "diagnosticLogs": {

      "samplingPercentage": 50,
      "alwaysLogErrors": true,
      "logClientIp": true,
      "verbosity": "error",
      "operationNameFormat": "Url",

      "frontendRequests": {
        "headersToLog": ["content-type", "accept", "origin"],
        "bodyBytes": "32"
      },

      "frontendResponse": {
        "headersToLog": ["content-type", "accept", "origin"],
        "bodyBytes": "32",
        "dataMasking": {
          "headers": {
            "mode": "Mask",
            "value": "content-type"
          },
          "queryParams": {
            "mode": "Mask",
            "value": "accept"
          }
        }
      },

      "backendRequest": {
        "headersToLog": ["content-type", "accept", "origin"],
        "bodyBytes": "32",
        "dataMasking": {
          "queryParams": {
            "mode": "Hide",
            "value": "origin"
          }
        }
      },

      "backendResponse": {
        "headersToLog": ["content-type", "accept", "origin"],
        "bodyBytes": "32"
      }
    }
  }
}

Default values

The table below shows default values for properties that are not set. If a property isn't listed in the table below, the default value is null.

Property	Default value
`apiRevision`	`1`
`subscriptionRequired`	`true`
`protocols`	`["https"]`

Default values for diagnosticLogs

The table below shows default values for properties that aren't explicity set under diagnosticLogs. If a property isn't listed in the table below, the default value is null.

Property	Default value
`samplingPercentage`	`100`
`alwaysLogErrors`	`false`
`logClientIp`	`true`
`verbosity`	`information`
`correlationProtocol`	`Legacy`
`operationNameFormat`	`Name`

Important information about apiInformation.json

Markdown and HTML are supported in the description field.
Use \n as a line break in the description field.
path is typically required. If you wish to publish an API without a path/API URL suffix, set the allow_api_without_path variable to true in the module. By default, it is set to false.
If APIM is published through for example Azure Front Door, and are forced to use to HTTPS, the use of http under protocols will result in a failure.
Changing the apiRevision will recreate the entire API. Therefore, it has no practical significance.
Tags defined in tags must be created prior to or simultaneously when creating the API. Refer to the tag name (not display name). See Tags for more information.
The API Version Set defined under apiVersionSet must be created prior to or simultaneously when creating the API. See API Version Set for more information.
Logging all events can significantly impact the performance of APIM, depending on the number of requests. Therefore, be cautious when setting the samplingPercentage under diagnosticLogs. Refer to Microsoft's article on the topic for more information: Performance implications and log sampling.

`specification.json` / `specification.yaml`

The file is typically generated by the application and must adhere to the OpenAPI specification.

`policy.xml`

Information about policy.xml (API)

Policies in Azure API Management can be assigned at different levels:

Globalt
Workspace
Product
API
Operation

The level being addressed here is API.

Useful links:

API Version Sets

Category	Path	File	Required / Optional	Description
API Version Sets	`<artifacts folder>/apiVersionSets/<api version set name>`	`apiVersionSetInformation.json`	Required	Information about each API Version Set.

For each API Version Set, a subfolder must be created as shown in the table above, where the name of the subfolder will be the name of the API Version Set.

`apiVersionSetInformation.json`

Example with minimum configuration

{
  "properties": {
    "displayName": "Lorem ipsum",
    "versioningScheme": "Segment"
  }
}

Example with all configuration

{
  "properties": {
    "displayName": "Lorem ipsum",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "versioningScheme": "Query",
    "versionHeaderName": null,
    "versionQueryName": "version"
  }
}

Important information about apiVersionSetInformation.json

versioningScheme can be configured with one of the following values:
- Header
- Query
- Segment
If versioningScheme is set to Header, versionHeaderName must be configured.
If versioningScheme is set to Query, versionQueryName must be configured.

Backends

Category	Path	File	Required / Optional	Description
Backends	`<artifacts folder>/backends/<backend name>`	`backendInformation.json`	Required	Information about each backend.

For each backend, a subfolder must be created as shown in the table above, where the name of the subfolder will be the name of the backend.

`backendInformation.json`

Example with minimum configuration

{
  "properties": {
    "url": "https://app-example-prod.azurewebsites.net/api/v3"
  }
}

Example with all configuration

{
  "properties": {
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "url": "https://app-example-prod.azurewebsites.net/api/v3",
    
    "validateCertificateChain": true,
    "validateCertificateName": true,

    "azureResourceManagerId": "https://management.azure.com/subscriptions/4cc5ebd5-f801-424c-8066-0d03fb4d90d7/resourceGroups/rg-example-prod/providers/Microsoft.Web/sites/func-example-prod",

    "credentials": {
      "headers": {
        "named-value-example": "{{name-of-named-value}}",
        "lorem-ipsum": "dolor-sit-amet"
      },
      "query": {
        "named-value-example": "{{name-of-named-value}}",
        "lorem-ipsum": "dolor-sit-amet"
      },
      "certificates": [
        "https://kv-example-prod.vault.azure.net/secrets/lorem-ipsum"
      ],
      "authorization": {
        "scheme": "Basic",
        "parameter": "username:password"
      }
    }
  }
}

Important information about backendInformation.json

When referring to an Azure resource as a backend, use the azureResourceManagerId property to refer to the Azure resource. The format must be as shown in the example above.
When headers or query need to refer to a named value, the name of the named value should be enclosed in double curly brackets {{}}, as shown in the example above.
The named value being referred to must be created prior to or simultaneously with the creation of the backend. Refer to Named values for more information.
Certificates being referred to must be created prior to or simultaneously with the creation of the backend. Refer to Certificates for more information.
Only support for HTTP backends is included in the module, not SOAP (but possible).
Support for backend proxies is not included in the module (but possible).
Support for Service Fabric is not included in the module (but possible).

Certificates

Category	Path	File	Required / Optional	Description
Certificates	`<artifacts folder>/certificates`	`certificatesInformation.json`	Required	Information about the certificates to be added.

All the information should be provided in the file as shown in the table above.

`certificatesInformation.json`

Example configuration

{
  "certificates": [
    "https://kv-example-prod.vault.azure.net/secrets/lorem-ipsum",
    "https://kv-example-dev.vault.azure.net/secrets/dolor-sit"
  ]
}

Important information about certificatesInformation.json

Each line in the list should reference a Key Vault certificate's secret ID.
APIM's System Managed Identity must have the Get access to the secret in Key Vault. No other access is required.
In most cases, we want to reference the secret ID without the version number appended. This way, the certificate will be automatically updated when it is renewed in Key Vault.
Refer to the secret without the trailing slash (i.e., without a forward slash at the end of the string).
The certificate must be of type application/x-pkcs12.

Groups

Category	Path	File	Required / Optional	Description
Groups	`<artifacts folder>/groups`	`groupsInformation.json`	Required	Information about the groups to be added.

All information should be entered into the file as shown in the table above.

`groupsInformation.json`

Example configuration

{
  "aad_groups": [
    "AzureAD-Group-01",
    "AzureAD-Group-02"
  ],
  "local_groups": [
    "Local-Group-on-APIM-01",
    "Local-Group-on-APIM-02"
  ]
}

Important information about groupsInformation.json

Azure AD groups are added under aad_groups. The group must exist in Azure AD.
Local groups on APIM are added under local_groups.

Named Values

Category	Path	File	Required / Optional	Description
Named Values	`<artifacts folder>/namedValues/<named value name>`	`namedValueInformation.json`	Required	Information about each Named Value.

For each Named Value, a subfolder must be created as shown in the table above, where the name of the subfolder will be the Named Value's name.

`namedValueInformation.json`

Example with reference to a Key Vault secret

{
  "properties": {
    "displayName": "lorem-ipsum",
    "keyVaultSecretId": "https://kv-example-prod.vault.azure.net/secrets/lorem-ipsum"
  }
}

Example with a value defined in the configuration file

{
  "properties": {
    "displayName": "lorem-ipsum",
    "value": "dolor-sit"
  }
}

Example with tags defined

{
  "properties": {
    "displayName": "lorem-ipsum",
    "value": "dolor-sit",
    "tags": [
      "tag1",
      "tag2"
    ]
  }
}

Important information about namedValueInformation.json

If the value is a secret, use a reference to a Key Vault.
APIM's System Managed Identity must have Get access to secrets in Key Vault. No other permissions are required.
Display name may contain only letters, digits, periods, dash, and underscore.

Products

Category	Path	File	Required / Optional	Description
Products	`<artifacts folder>/products/<product name>`	`productInformation.json`	Required	Information about each individual Product.
Products	`<artifacts folder>/products/<product name>`	`policy.xml`	Optional	Policy for the Product.

For each Product, a subfolder must be created as shown in the table above, where the subfolder name will be the name of the Product.

`productInformation.json`

Example with minimum configuration

{
  "properties": {
    "displayName": "Lorem ipsum",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "published": true,
    "subscriptionRequired": false,
    "approvalRequired": false
  }
}

Example with all configuration

{
  "properties": {
    "displayName": "Lorem ipsum",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
    "published": true,
    "subscriptionRequired": true,
    "approvalRequired": false,
    "subscriptionsLimit": 3,
    "terms": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Ut turpis velit, vehicula non fermentum elementum, elementum ac felis.",
    "apis": [
      "conference",
      "petstore"
    ],
    "groups": [
      "Developers",
      "AzureAD-Group-01",
      "Local-Group-on-APIM-01"
    ],
    "tags": [
      "tag1",
      "tag2"
    ]
  }
}

Important information about productInformation.json

The API referenced must be created prior to or at the same time as the Product. See APIs.
The Groups referenced must be created prior to or at the same time as the Product. See Groups.
The Tags referenced must be created prior to or at the same time as the Product. See Tags. Refer to the tag name (not the display name).
The subscriptionsLimit can only be set when subscriptionRequired is set to true.
The Terms property represents the Terms and Conditions for this Product, which developers must accept before they can begin the Subscription process.

`policy.xml`

Information about policy.xml (Product)

Policies in Azure API Management can be assigned at different levels:

Globalt
Workspace
Product
API
Operation

The level being addressed here is Product.

Useful links:

Users and Group Memberships

User Accounts:
- If enabled, users can register through the self-service sign-up in the Developer Portal.
- Azure AD users who log in are automatically added upon their first login.
Group Memberships:
- Membership in local groups is managed outside of APIM APIOps.
- Membership in Azure AD groups is managed in Azure AD.

Other areas

Other areas in Azure API Management, such as workspaces and authorizations, are not yet supported in the module. Please open an issue or contribute through a pull request if needed.

If you any questions, feel free to ask through issues in GitHub.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

02 What can be managed by APIM APIOps?

APIs

`apiInformation.json`

`specification.json` / `specification.yaml`

`policy.xml`

API Version Sets

`apiVersionSetInformation.json`

Backends

`backendInformation.json`

Certificates

`certificatesInformation.json`

Groups

`groupsInformation.json`

Named Values

`namedValueInformation.json`

Products

`productInformation.json`

`policy.xml`

Tags

`tagsInformation.json`

Users and Group Memberships

Other areas

Clone this wiki locally

02 What can be managed by APIM APIOps?

APIs

apiInformation.json

specification.json / specification.yaml

policy.xml

API Version Sets

apiVersionSetInformation.json

Backends

backendInformation.json

Certificates

certificatesInformation.json

Groups

groupsInformation.json

Named Values

namedValueInformation.json

Products

productInformation.json

policy.xml

Tags

tagsInformation.json

Users and Group Memberships

Other areas

Clone this wiki locally

`apiInformation.json`

`specification.json` / `specification.yaml`

`policy.xml`

`apiVersionSetInformation.json`

`backendInformation.json`

`certificatesInformation.json`

`groupsInformation.json`

`namedValueInformation.json`

`productInformation.json`

`policy.xml`

`tagsInformation.json`