Skip to content

Latest commit

 

History

History
48 lines (36 loc) · 1.33 KB

reserved-resource-names-model-as-enum.md

File metadata and controls

48 lines (36 loc) · 1.33 KB

ReservedResourceNamesModelAsEnum

Category

ARM Warning

Applies to

ARM OpenAPI (swagger) specs

Related ARM Guideline Code

  • RPC-ConstrainedCollections-V1-04

Description

Service-defined (reserved) resource names must be represented as an enum type with modelAsString set to true, not as a static string in the path. This is to allow for expansion of the resource collection to include more service defined instances in future if necessary. Changing the representation of the path in swagger to an enum does not require you to change the implementation of the API in the service. Adhering to this best practice helps with forward compatibility and avoids potential breaking changes in future revisions of the API.

How to fix the violation

Instead of using a reserved name at the end of the path, use a path parameter. E.g.,

- "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Bakery/breads/defaultBread"
+ "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Bakery/breads/{breadName}"
"BreadName": {
  "name": "breadName",
  "type": "string",
  "description": "The type of bread.",
  "enum": [
    "baguette",
    "brioche",
    "sourdough",
    "rye"
  ],
  "x-ms-enum": {
    "name": "breadName",
    "modelAsString": true
  }
}