Skip to content

Use API descriptors#

Operational Excellence · API Management · Rule · 2020_09 · Awareness

APIs should have a display name and description.

Description#

Each API 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 and consumer perspectives:

  • Having a clear understanding of the purpose of an API is often important to during analysis.
  • Allows for accurate management and clean up of unused APIs.

This information is visible within the developer portal and exported OpenAPI definitions.

Recommendation#

Consider using display name and description fields on APIs 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 APIs 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/apis",
  "apiVersion": "2022-08-01",
  "name": "[format('{0}/{1}', parameters('name'), 'echo-v1')]",
  "properties": {
    "displayName": "Echo API",
    "description": "An echo API service.",
    "type": "http",
    "path": "echo",
    "serviceUrl": "https://echo.contoso.com",
    "protocols": [
      "https"
    ],
    "apiVersion": "v1",
    "apiVersionSetId": "[resourceId('Microsoft.ApiManagement/service/apiVersionSets', parameters('name'), 'echo')]",
    "subscriptionRequired": true
  },
  "dependsOn": [
    "[resourceId('Microsoft.ApiManagement/service', parameters('name'))]",
    "[resourceId('Microsoft.ApiManagement/service/apiVersionSets', parameters('name'), 'echo')]"
  ]
}

Configure with Bicep#

To deploy API Management APIs 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 api 'Microsoft.ApiManagement/service/apis@2022-08-01' = {
  parent: service
  name: 'echo-v1'
  properties: {
    displayName: 'Echo API'
    description: 'An echo API service.'
    type: 'http'
    path: 'echo'
    serviceUrl: 'https://echo.contoso.com'
    protocols: [
      'https'
    ]
    apiVersion: 'v1'
    apiVersionSetId: version.id
    subscriptionRequired: true
  }
}

Comments