Skip to content

Use product descriptors#

Operational Excellence · API Management · Rule · 2020_09

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

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:

Azure Template snippet
{
  "type": "Microsoft.ApiManagement/service/products",
  "apiVersion": "2021-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:

Azure Bicep snippet
resource product 'Microsoft.ApiManagement/service/products@2021-08-01' = {
  parent: service
  name: 'echo'
  properties: {
    displayName: 'Echo'
    description: 'Echo API services for Contoso.'
    approvalRequired: true
    subscriptionRequired: true
  }
}
Last update: 2023-03-07

Comments