|
| 1 | +--- |
| 2 | +applyTo: "**/specification/**/resource-manager/*.json" |
| 3 | +--- |
| 4 | + |
| 5 | +# ARM OpenAPI (Swagger) Review Instructions |
| 6 | + |
| 7 | +When reviewing Azure Resource Manager (ARM) OpenAPI specifications, ensure compliance with Microsoft API |
| 8 | +Guidelines and Azure RPC contracts. Prioritize Azure RPC requirements when conflicts arise. |
| 9 | + |
| 10 | +## Critical Requirements |
| 11 | + |
| 12 | +### 1. API Guidelines Compliance |
| 13 | + |
| 14 | +- **MUST** follow [Azure REST API Guidelines] |
| 15 | + (https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md) |
| 16 | +- **MUST** conform to [Azure RPC contracts] |
| 17 | + (https://github.com/cloud-and-ai-microsoft/resource-provider-contract) |
| 18 | +- Azure RPC takes precedence over general guidelines in case of conflicts |
| 19 | + |
| 20 | +### 2. Breaking Changes Prevention |
| 21 | + |
| 22 | +- **NO breaking changes** in GA (stable) API versions per |
| 23 | + [Azure Breaking Changes Policy](https://aka.ms/AzBreakingChangesPolicy) |
| 24 | +- Verify no removal/renaming of properties, operations, or parameters in existing versions |
| 25 | +- Check property types remain unchanged (e.g., boolean → string is breaking) |
| 26 | +- Ensure enum values are not removed or renamed |
| 27 | +- New required properties or parameters require new API version |
| 28 | +- URL path format changes require new API version |
| 29 | + |
| 30 | +### 3. ARM Resource Model Requirements |
| 31 | + |
| 32 | +- Resource model name **MUST** match singular form of resource type (e.g., `VirtualMachine` for `virtualMachines`) |
| 33 | +- Top-level resources **MUST** have `ListByResourceGroup` and `ListBySubscription` operations |
| 34 | +- Tracked resources **MUST** have GET, PUT, PATCH (update), and DELETE operations |
| 35 | +- All resources **MUST** include `systemData` property (read-only) with type from common-types |
| 36 | +- Nested resources **MUST** have List operation |
| 37 | + |
| 38 | +### 4. Common Types Usage |
| 39 | + |
| 40 | +- **MUST** reference appropriate common-types version (v3, v4, or v5) for standard ARM types: |
| 41 | + - `Resource`, `TrackedResource`, `ProxyResource`, `ExtensionResource` |
| 42 | + - `ErrorResponse`, `ErrorDetail` |
| 43 | + - Standard parameters: `SubscriptionIdParameter`, `ResourceGroupNameParameter`, `ApiVersionParameter` |
| 44 | +- Use `$ref` to common-types instead of redefining standard ARM structures |
| 45 | + |
| 46 | +### 5. API Versioning |
| 47 | + |
| 48 | +- API version **MUST** follow `YYYY-MM-DD` format |
| 49 | +- Version **MUST** be in path: |
| 50 | + `/subscriptions/{subscriptionId}/providers/Microsoft.{Namespace}/...?api-version=YYYY-MM-DD` |
| 51 | +- Stable versions in `/stable/` directory, preview in `/preview/` |
| 52 | + |
| 53 | +### 6. Security & Authentication |
| 54 | + |
| 55 | +- **MUST** define `securityDefinitions` with OAuth2 Azure AD authentication |
| 56 | +- **MUST** apply `security` requirement to all operations |
| 57 | +- Scopes should use `user_impersonation` for management plane |
| 58 | + |
| 59 | +### 7. Property & Parameter Correctness |
| 60 | + |
| 61 | +- Mark required parameters as `"required": true` - incorrect marking breaks customers |
| 62 | +- Mark read-only properties as `"readOnly": true` (e.g., `id`, `name`, `type`, `systemData`) |
| 63 | +- Use `x-ms-mutability` to specify create/read/update behavior |
| 64 | +- Collections **MUST** support multiple elements, not artificially limited to one |
| 65 | +- Only define operations/properties/parameters actually supported by the service |
| 66 | + |
| 67 | +### 8. Naming Conventions |
| 68 | + |
| 69 | +- Properties and parameters: **camelCase** (e.g., `resourceGroupName`) |
| 70 | +- Resource types in path: **camelCase** (e.g., `/virtualMachines/{virtualMachineName}`) |
| 71 | +- Resource provider namespace: **PascalCase** (e.g., `Microsoft.Compute`) |
| 72 | +- Model definitions: **PascalCase** (e.g., `VirtualMachine`) |
| 73 | +- Enum values: **PascalCase** preferred |
| 74 | +- Avoid abbreviations in names unless industry-standard |
| 75 | +- Use resource name, not abbreviations, in path parameters: `{virtualMachineName}` not `{vmName}` |
| 76 | + |
| 77 | +### 9. Operations & Operation IDs |
| 78 | + |
| 79 | +- OperationId format: `{ResourceType}_{Action}` (e.g., `VirtualMachines_Get`, `VirtualMachines_CreateOrUpdate`) |
| 80 | +- Operations **MUST** have unique `operationId` |
| 81 | +- Use standard verbs: GET → `Get/List`, PUT → `CreateOrUpdate`, PATCH → `Update`, DELETE → `Delete`, POST → action name |
| 82 | +- Include `x-ms-examples` referencing example JSON files |
| 83 | +- DELETE operations: return 200 (with body), 202 (async), or 204 (no content) |
| 84 | +- Long-running operations: use `x-ms-long-running-operation: true` and return 201 or 202 |
| 85 | + |
| 86 | +### 10. Pagination & Collections |
| 87 | + |
| 88 | +- List operations **MUST** use `x-ms-pageable` with `nextLinkName` |
| 89 | +- Collection models **MUST** have `value` array property and optional `nextLink` string |
| 90 | + |
| 91 | +### 11. Documentation Quality |
| 92 | + |
| 93 | +- Every operation, parameter, property, and model **MUST** have clear description |
| 94 | +- Start operation descriptions with verb (e.g., "Gets the virtual machine.") |
| 95 | +- Start with capital letter, end with period |
| 96 | +- Specify units for quantifiable properties (MB, seconds, etc.) |
| 97 | +- Use correct acronym capitalization: "URL" not "Url", "ID" not "Id" |
| 98 | +- Avoid: "Gets or sets...", "Gets...", "Sets..." in property descriptions |
| 99 | +- Document all HTTP status codes in responses |
| 100 | + |
| 101 | +### 12. Error Handling |
| 102 | + |
| 103 | +- Default error response **MUST** reference common-types `ErrorResponse` |
| 104 | +- Include "default" response for all operations |
| 105 | +- Use `x-ms-error-response: true` for error responses |
| 106 | + |
| 107 | +### 13. Extensions & Special Features |
| 108 | + |
| 109 | +- **REQUIRED**: `x-ms-parameter-location: "method"` for common parameters |
| 110 | + (subscriptionId, resourceGroupName, apiVersion) |
| 111 | +- Use `x-ms-enum` with `modelAsString: true` for extensible enums (allows new values without breaking) |
| 112 | +- Use `x-ms-discriminator-value` for polymorphic types |
| 113 | +- Private/internal operations: mark with `x-ms-visibility: "internal"` |
| 114 | + |
| 115 | +### 14. Customer Usability |
| 116 | + |
| 117 | +Think as a customer: Are parameter names intuitive? Is required vs. optional clear? Are default values |
| 118 | +documented? Can developers understand how to use this API from the specification alone? |
| 119 | + |
| 120 | +### 15. Examples & Testing |
| 121 | + |
| 122 | +- **MUST** include `x-ms-examples` for all operations |
| 123 | +- Example files in `examples/` directory |
| 124 | +- **MUST** test all operations before PR submission |
| 125 | +- Examples **MUST** validate against specification |
| 126 | + |
| 127 | +## Review Checklist Summary |
| 128 | + |
| 129 | +✓ No breaking changes in existing versions |
| 130 | +✓ Follows Azure RPC contracts |
| 131 | +✓ Common-types properly referenced |
| 132 | +✓ Naming conventions (camelCase properties, PascalCase types) |
| 133 | +✓ Required/readOnly correctly marked |
| 134 | +✓ Security definitions present |
| 135 | +✓ Standard ARM operations implemented |
| 136 | +✓ Pagination on list operations |
| 137 | +✓ Operation IDs follow pattern |
| 138 | +✓ Examples provided and valid |
| 139 | +✓ Descriptions clear and complete |
| 140 | +✓ API version format correct |
| 141 | + |
| 142 | +Flag violations clearly with line numbers and specific guidance for fixes. |
| 143 | +Once completed always add the following comment : "Copilot used the entire file : .github/instructions/armapi-review.instructions.md for arm api reviews." |
0 commit comments