Use product descriptors

March 21, 2025 ยท View on GitHub

SYNOPSIS

API Management products should have a display name and description.

DESCRIPTION

Each product created in API Management can have a display name and description set. Using easy to understand descriptions and metadata greatly assists identification for management and usage.

During monitoring from service provider perspective:

  • Having a clear understanding of the purpose of a product is often important to during analysis.
  • Allows for accurate management and clean up of unused or old products.
  • Allows for accurate access control decisions.

This information is visible within the developer portal. Accurate information can be used to assist developers in understanding the purpose of a product.

RECOMMENDATION

Consider using display name and description fields on products to convey intended purpose and usage. Display name and description fields should be human readable and easy to understand.

EXAMPLES

Configure with Azure template

To deploy API Management Products that pass this rule:

  • Set the properties.displayName with a human readable name.
  • Set the properties.description with an description of the APIs purpose.

For example:

{
  "type": "Microsoft.ApiManagement/service/products",
  "apiVersion": "2022-08-01",
  "name": "[format('{0}/{1}', parameters('name'), 'echo')]",
  "properties": {
    "displayName": "Echo",
    "description": "Echo API services for Contoso.",
    "approvalRequired": true,
    "subscriptionRequired": true
  },
  "dependsOn": [
    "[resourceId('Microsoft.ApiManagement/service', parameters('name'))]"
  ]
}

Configure with Bicep

To deploy API Management Products that pass this rule:

  • Set the properties.displayName with a human readable name.
  • Set the properties.description with an description of the APIs purpose.

For example:

resource product 'Microsoft.ApiManagement/service/products@2022-08-01' = {
  parent: service
  name: 'echo'
  properties: {
    displayName: 'Echo'
    description: 'Echo API services for Contoso.'
    approvalRequired: true
    subscriptionRequired: true
  }
}