Skip to content

Commit

Permalink
Update common types with Operation + OperationListResult (Azure#11356)
Browse files Browse the repository at this point in the history 
* Add titles and descriptions for 'commontypes/v1/Resource' common types.

* Define the 'Operation' and 'OperationListResult' common types in common-types v1.

* REFATOR: Update 'redis.json' to use common-types v1 OperationListResult.

* Revert "REFATOR: Update 'redis.json' to use common-types v1 OperationListResult." which the linter breaking change the detection wasn't a fan of.

This reverts commit f8f696f.

* Improvements to descriptions, and 'readOnly' annotations on OperationListResult

* Fix typo in the Resource description.

* Also add the Operation definition to common-types' v2/types.json, along with most of the improvements to descriptions etc.

* Revise descriptions with API consumers as intended audience.
  • Loading branch information
@TimLovellSmith
TimLovellSmith authored and giromm2ms committed Dec 20, 2020
1 parent 9669b4d commit c0fa9da
Show file tree
Hide file tree
Showing 2 changed files with 198 additions and 21 deletions.
112 changes: 102 additions & 10 deletions specification/common-types/resource-management/v1/types.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,13 @@
"paths": {},
"definitions": {
"Resource": {
"title": "Resource",
"description": "Common fields that are returned in the response for all Azure Resource Manager resources",
"properties": {
"id": {
"readOnly": true,
"type": "string",
"description": "Fully qualified resource Id for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
"description": "Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
},
"name": {
"readOnly": true,
Expand All @@ -21,14 +23,15 @@
"type": {
"readOnly": true,
"type": "string",
"description": "The type of the resource. Ex- Microsoft.Compute/virtualMachines or Microsoft.Storage/storageAccounts."
"description": "The type of the resource. E.g. \"Microsoft.Compute/virtualMachines\" or \"Microsoft.Storage/storageAccounts\""
}
},
"x-ms-azure-resource": true
},
"AzureEntityResource": {
"x-ms-client-name": "AzureEntityResource",
"description": "The resource model definition for a Azure Resource Manager resource with an etag.",
"title": "Entity Resource",
"description": "The resource model definition for an Azure Resource Manager resource with an etag.",
"properties": {
"etag": {
"type": "string",
Expand All @@ -43,7 +46,8 @@
]
},
"TrackedResource": {
"description": "The resource model definition for a ARM tracked top level resource",
"title": "Tracked Resource",
"description": "The resource model definition for an Azure Resource Manager tracked top level resource which has 'tags' and a 'location'",
"properties": {
"tags": {
"type": "object",
Expand Down Expand Up @@ -76,7 +80,8 @@
]
},
"ProxyResource": {
"description": "The resource model definition for a ARM proxy resource. It will have everything other than required location and tags",
"title": "Proxy Resource",
"description": "The resource model definition for a Azure Resource Manager proxy resource. It will not have tags and a location",
"allOf": [
{
"$ref": "#/definitions/Resource"
Expand All @@ -92,7 +97,7 @@
"x-ms-mutability": [
"read"
],
"description": "Fully qualified resource Id for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
"description": "Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
},
"name": {
"readOnly": true,
Expand All @@ -105,7 +110,7 @@
"x-ms-mutability": [
"read"
],
"description": "The type of the resource. Ex- Microsoft.Compute/virtualMachines or Microsoft.Storage/storageAccounts.."
"description": "The type of the resource. E.g. \"Microsoft.Compute/virtualMachines\" or \"Microsoft.Storage/storageAccounts\""
},
"location": {
"type": "string",
Expand Down Expand Up @@ -270,6 +275,8 @@
]
},
"ErrorResponse": {
"title": "Error Response",
"description": "Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.)",
"properties": {
"code": {
"readOnly": true,
Expand Down Expand Up @@ -302,8 +309,7 @@
},
"description": "The error additional info."
}
},
"description": "The resource management error response."
}
},
"ErrorAdditionalInfo": {
"properties": {
Expand All @@ -320,6 +326,92 @@
},
"description": "The resource management error additional info."
},
"Operation": {
"title": "REST API Operation",
"description": "Details of a REST API operation, returned from the Resource Provider Operations API",
"type": "object",
"properties": {
"name": {
"description": "The name of the operation, as per Resource-Based Access Control (RBAC). Examples: \"Microsoft.Compute/virtualMachines/write\", \"Microsoft.Compute/virtualMachines/capture/action\"",
"type": "string",
"readOnly": true
},
"isDataAction": {
"description": "Whether the operation applies to data-plane. This is \"true\" for data-plane operations and \"false\" for ARM/control-plane operations.",
"type": "boolean",
"readOnly": true
},
"display": {
"description": "Localized display information for this particular operation.",
"properties": {
"provider": {
"description": "The localized friendly form of the resource provider name, e.g. \"Microsoft Monitoring Insights\" or \"Microsoft Compute\".",
"type": "string",
"readOnly": true
},
"resource": {
"description": "The localized friendly name of the resource type related to this operation. E.g. \"Virtual Machines\" or \"Job Schedule Collections\".",
"type": "string",
"readOnly": true
},
"operation": {
"description": "The concise, localized friendly name for the operation; suitable for dropdowns. E.g. \"Create or Update Virtual Machine\", \"Restart Virtual Machine\".",
"type": "string",
"readOnly": true
},
"description": {
"description": "The short, localized friendly description of the operation; suitable for tool tips and detailed views.",
"type": "string",
"readOnly": true
}
}
},
"origin": {
"description": "The intended executor of the operation; as in Resource Based Access Control (RBAC) and audit logs UX. Default value is \"user,system\"",
"type": "string",
"readOnly": true,
"enum": [
"user",
"system",
"user,system"
],
"x-ms-enum": {
"name": "Origin",
"modelAsString": true
}
},
"actionType": {
"description": "Enum. Indicates the action type. \"Internal\" refers to actions that are for internal only APIs.",
"type": "string",
"readOnly": true,
"enum": [
"Internal"
],
"x-ms-enum": {
"name": "ActionType",
"modelAsString": true
}
}
}
},
"OperationListResult": {
"description": "A list of REST API operations supported by an Azure Resource Provider. It contains an URL link to get the next set of results.",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/definitions/Operation"
},
"description": "List of operations supported by the resource provider",
"readOnly": true
},
"nextLink": {
"type": "string",
"description": "URL to get the next set of operation list results (if there are any).",
"readOnly": true
}
}
},
"locationData": {
"description": "Metadata pertaining to the geographic location of the resource.",
"type": "object",
Expand Down Expand Up @@ -429,7 +521,7 @@
"type": "string"
},
"identity": {
"description": "The client id of the identity which will be used to access key vault.",
"description": "The client ID of the identity which will be used to access key vault.",
"type": "string"
}
}
Expand Down
107 changes: 96 additions & 11 deletions specification/common-types/resource-management/v2/types.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,12 @@
"paths": {},
"definitions": {
"Resource": {
"description": "Common fields that are returned in the response for all Azure Resource Manager resources",
"properties": {
"id": {
"readOnly": true,
"type": "string",
"description": "Fully qualified resource Id for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
"description": "Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
},
"name": {
"readOnly": true,
Expand All @@ -21,15 +22,14 @@
"type": {
"readOnly": true,
"type": "string",
"description": "The type of the resource. Ex- Microsoft.Compute/virtualMachines or Microsoft.Storage/storageAccounts."
"description": "The type of the resource. E.g. \"Microsoft.Compute/virtualMachines\" or \"Microsoft.Storage/storageAccounts\""
}
},
"description": "The resource model definition for a ARM tracked top level resource",
"x-ms-azure-resource": true
},
"AzureEntityResource": {
"x-ms-client-name": "AzureEntityResource",
"description": "The resource model definition for a Azure Resource Manager resource with an etag.",
"description": "The resource model definition for an Azure Resource Manager resource with an etag.",
"properties": {
"etag": {
"type": "string",
Expand All @@ -44,7 +44,7 @@
]
},
"TrackedResource": {
"description": "The resource model definition for a ARM tracked top level resource",
"description": "The resource model definition for an Azure Resource Manager tracked top level resource",
"properties": {
"tags": {
"type": "object",
Expand Down Expand Up @@ -77,7 +77,7 @@
]
},
"ProxyResource": {
"description": "The resource model definition for a ARM proxy resource. It will have everything other than required location and tags",
"description": "The resource model definition for an Azure Resource Manager proxy resource. It will have everything other than required location and tags",
"allOf": [
{
"$ref": "#/definitions/Resource"
Expand All @@ -93,7 +93,7 @@
"x-ms-mutability": [
"read"
],
"description": "Fully qualified resource Id for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
"description": "Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}"
},
"name": {
"readOnly": true,
Expand All @@ -106,7 +106,7 @@
"x-ms-mutability": [
"read"
],
"description": "The type of the resource. Ex- Microsoft.Compute/virtualMachines or Microsoft.Storage/storageAccounts.."
"description": "The type of the resource. E.g. \"Microsoft.Compute/virtualMachines\" or \"Microsoft.Storage/storageAccounts\""
},
"location": {
"type": "string",
Expand All @@ -123,7 +123,7 @@
"create",
"update"
],
"description": "The fully qualified resource ID of the resource that manages this resource. Indicates if this resource is managed by another azure resource. If this is present, complete mode deployment will not delete the resource if it is removed from the template since it is managed by another resource."
"description": "The fully qualified resource ID of the resource that manages this resource. Indicates if this resource is managed by another Azure resource. If this is present, complete mode deployment will not delete the resource if it is removed from the template since it is managed by another resource."
},
"kind": {
"type": "string",
Expand Down Expand Up @@ -207,7 +207,7 @@
"capacity": {
"type": "integer",
"format": "int32",
"description": "If the SKU supports scale out/in then the capacity integer should be included. If scale out/in is not possible for the resource this may be omitted."
"description": "If the SKU supports scale out/in then the capacity integer indicates the current scaling-factor of the resource. If scale out/in is not possible for the resource this may be omitted."
}
},
"required": [
Expand Down Expand Up @@ -327,6 +327,91 @@
},
"description": "The resource management error additional info."
},
"Operation": {
"description": "Details of a REST API operation, returned from the Resource Provider Operations API",
"type": "object",
"properties": {
"name": {
"description": "The name of the operation, as per Resource-Based Access Control (RBAC). Examples: \"Microsoft.Compute/virtualMachines/write\", \"Microsoft.Compute/virtualMachines/capture/action\"",
"type": "string",
"readOnly": true
},
"isDataAction": {
"description": "Whether the operation applies to data-plane. This is \"true\" for data-plane operations and \"false\" for ARM/control-plane operations.",
"type": "boolean",
"readOnly": true
},
"display": {
"description": "Localized display information for this particular operation.",
"properties": {
"provider": {
"description": "The localized friendly form of the resource provider name, e.g. \"Microsoft Monitoring Insights\" or \"Microsoft Compute\".",
"type": "string",
"readOnly": true
},
"resource": {
"description": "The localized friendly name of the resource type related to this operation. E.g. \"Virtual Machines\" or \"Job Schedule Collections\".",
"type": "string",
"readOnly": true
},
"operation": {
"description": "The concise, localized friendly name for the operation; suitable for dropdowns. E.g. \"Create or Update Virtual Machine\", \"Restart Virtual Machine\".",
"type": "string",
"readOnly": true
},
"description": {
"description": "The short, localized friendly description of the operation; suitable for tool tips and detailed views.",
"type": "string",
"readOnly": true
}
}
},
"origin": {
"description": "The intended executor of the operation; as in Resource Based Access Control (RBAC) and audit logs UX. Default value is \"user,system\"",
"type": "string",
"readOnly": true,
"enum": [
"user",
"system",
"user,system"
],
"x-ms-enum": {
"name": "Origin",
"modelAsString": true
}
},
"actionType": {
"description": "Enum. Indicates the action type. \"Internal\" refers to actions that are for internal only APIs.",
"type": "string",
"readOnly": true,
"enum": [
"Internal"
],
"x-ms-enum": {
"name": "ActionType",
"modelAsString": true
}
}
}
},
"OperationListResult": {
"description": "A list of REST API operations supported by an Azure Resource Provider. It contains an URL link to get the next set of results.",
"properties": {
"value": {
"type": "array",
"items": {
"$ref": "#/definitions/Operation"
},
"description": "List of operations supported by the resource provider",
"readOnly": true
},
"nextLink": {
"type": "string",
"description": "URL to get the next set of operation list results (if there are any).",
"readOnly": true
}
}
},
"locationData": {
"description": "Metadata pertaining to the geographic location of the resource.",
"type": "object",
Expand Down Expand Up @@ -436,7 +521,7 @@
"type": "string"
},
"identity": {
"description": "The client id of the identity which will be used to access key vault.",
"description": "The client ID of the identity which will be used to access key vault.",
"type": "string"
}
}
Expand Down

0 comments on commit c0fa9da

Please sign in to comment.