Release sql microsoft.sql 2024 05 01 preview #30165
Dev/ivarandj/instance pool operations api (#29932)
* Add instance pool operations swagger and examples * Address prettier check errors * Fix Swagger LintDiff errors * Fix parameter names to match parameter patterns * Remove validation for resourceGroupName parameter as it fails Swagger ModelValidation (and it should not be failing) * Replace bool with enum (PR review remark) --------- Co-authored-by: Ivan Arandjelovic <[email protected]>
- Loading branch information
commit c145fd61a0e8190f67bf64cd5b30103e6696cea4
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,272 @@ | ||
| { | ||
| "swagger": "2.0", | ||
| "info": { | ||
| "version": "2024-05-01-preview", | ||
| "title": "SqlManagementClient", | ||
| "description": "The Azure SQL Database management API provides a RESTful set of web APIs that interact with Azure SQL Database services to manage your databases. The API enables users to create, retrieve, update, and delete databases, servers, and other entities." | ||
| }, | ||
| "host": "management.azure.com", | ||
| "schemes": [ | ||
| "https" | ||
| ], | ||
| "consumes": [ | ||
| "application/json" | ||
| ], | ||
| "produces": [ | ||
| "application/json" | ||
| ], | ||
| "paths": { | ||
| "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/instancePools/{instancePoolName}/operations": { | ||
| "get": { | ||
| "tags": [ | ||
| "InstancePoolOperations" | ||
| ], | ||
| "description": "Gets a list of operations performed on the instance pool.", | ||
| "operationId": "InstancePoolOperations_ListByInstancePool", | ||
| "parameters": [ | ||
| { | ||
| "$ref": "../../../common/v1/types.json#/parameters/ResourceGroupParameter" | ||
| }, | ||
| { | ||
| "name": "instancePoolName", | ||
|
There was a problem hiding this comment. can we reuse this across instancePools.json and intancePoolOperation.json. We are duplicating this |
||
| "in": "path", | ||
| "description": "The name of the managed instance pool.", | ||
| "required": true, | ||
| "type": "string", | ||
| "maxLength": 127, | ||
| "minLength": 1, | ||
| "pattern": "^[a-z0-9]+(-*[a-z0-9]+)*$" | ||
| }, | ||
| { | ||
| "$ref": "../../../common/v1/types.json#/parameters/SubscriptionIdParameter" | ||
| }, | ||
| { | ||
| "$ref": "../../../common/v1/types.json#/parameters/ApiVersionParameter" | ||
| } | ||
|
Contributor
There was a problem hiding this comment. use from common-types latest |
||
| ], | ||
| "responses": { | ||
| "200": { | ||
| "description": "The request for getting instance pool operations has been executed successfully.", | ||
| "schema": { | ||
| "$ref": "#/definitions/InstancePoolOperationListResult" | ||
| } | ||
| }, | ||
| "default": { | ||
| "description": "*** Error Responses: ***\n\n * 400 ManagedInstanceStoppingOrStopped - Conflicting operation submitted while instance is in stopping/stopped state\n\n * 400 ManagedInstanceStarting - Conflicting operation submitted while instance is in starting state\n\n * 404 SubscriptionDoesNotHaveServer - The requested server was not found\n\n * 404 ServerNotInSubscriptionResourceGroup - Specified server does not exist in the specified resource group and subscription.", | ||
| "schema": { | ||
| "$ref": "../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" | ||
| } | ||
| } | ||
| }, | ||
| "x-ms-pageable": { | ||
| "nextLinkName": "nextLink" | ||
| }, | ||
| "x-ms-examples": { | ||
| "List the instance pool management operations with no results": { | ||
| "$ref": "./examples/ListInstancePoolOperationsEmpty.json" | ||
| }, | ||
| "List the instance pool management operations with some results": { | ||
| "$ref": "./examples/ListInstancePoolOperations.json" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Sql/instancePools/{instancePoolName}/operations/{operationId}": { | ||
ivanarandjelovic marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "get": { | ||
| "tags": [ | ||
| "InstancePoolOperations" | ||
| ], | ||
| "description": "Gets a management operation on a instance pool.", | ||
| "operationId": "InstancePoolOperations_Get", | ||
| "parameters": [ | ||
| { | ||
| "$ref": "../../../common/v1/types.json#/parameters/ResourceGroupParameter" | ||
ivanarandjelovic marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| }, | ||
| { | ||
| "name": "instancePoolName", | ||
|
|
||
| "in": "path", | ||
| "description": "The name of the managed instance pool.", | ||
| "required": true, | ||
| "type": "string", | ||
| "maxLength": 127, | ||
| "minLength": 1, | ||
| "pattern": "^[a-z0-9]+(-*[a-z0-9]+)*$" | ||
| }, | ||
| { | ||
| "name": "operationId", | ||
| "in": "path", | ||
| "required": true, | ||
| "type": "string", | ||
| "format": "uuid" | ||
| }, | ||
| { | ||
| "$ref": "../../../common/v1/types.json#/parameters/SubscriptionIdParameter" | ||
| }, | ||
| { | ||
| "$ref": "../../../common/v1/types.json#/parameters/ApiVersionParameter" | ||
| } | ||
ivanarandjelovic marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| ], | ||
| "responses": { | ||
| "200": { | ||
| "description": "Successfully retrieved the specified instance pool operation.", | ||
| "schema": { | ||
| "$ref": "#/definitions/InstancePoolOperation" | ||
| } | ||
| }, | ||
| "default": { | ||
| "description": "*** Error Responses: ***\n\n * 400 ManagedInstanceStoppingOrStopped - Conflicting operation submitted while instance is in stopping/stopped state\n\n * 400 ManagedInstanceStarting - Conflicting operation submitted while instance is in starting state\n\n * 404 SubscriptionDoesNotHaveServer - The requested server was not found\n\n * 404 ServerNotInSubscriptionResourceGroup - Specified server does not exist in the specified resource group and subscription.\n\n * 404 ResourceNotFound - The requested resource was not found.", | ||
| "schema": { | ||
| "$ref": "../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse" | ||
| } | ||
| } | ||
| }, | ||
| "x-ms-examples": { | ||
| "Gets the instance pool management operation": { | ||
| "$ref": "./examples/GetInstancePoolOperation.json" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "definitions": { | ||
| "InstancePoolOperation": { | ||
| "description": "A instance pool operation.", | ||
| "type": "object", | ||
| "allOf": [ | ||
| { | ||
| "$ref": "../../../common/v1/types.json#/definitions/ProxyResource" | ||
ivanarandjelovic marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| } | ||
| ], | ||
| "properties": { | ||
| "properties": { | ||
| "$ref": "#/definitions/InstancePoolOperationProperties", | ||
| "description": "Resource properties.", | ||
| "x-ms-client-flatten": true | ||
|
There was a problem hiding this comment.
Contributor
There was a problem hiding this comment. is this still needed and why ? |
||
| } | ||
| } | ||
| }, | ||
| "InstancePoolOperationListResult": { | ||
| "description": "The response to a list instance pool operations request", | ||
| "type": "object", | ||
| "properties": { | ||
| "value": { | ||
| "description": "Array of results.", | ||
| "type": "array", | ||
| "items": { | ||
| "$ref": "#/definitions/InstancePoolOperation" | ||
| }, | ||
| "readOnly": true | ||
| }, | ||
| "nextLink": { | ||
| "description": "Link to retrieve next page of results.", | ||
| "type": "string", | ||
| "readOnly": true | ||
| } | ||
| } | ||
| }, | ||
| "InstancePoolOperationProperties": { | ||
| "description": "The properties of a instance pool operation.", | ||
| "type": "object", | ||
| "properties": { | ||
| "instancePoolName": { | ||
| "description": "The name of the instance pool the operation is being performed on.", | ||
| "type": "string", | ||
| "readOnly": true | ||
| }, | ||
| "operation": { | ||
| "description": "The name of operation.", | ||
| "type": "string", | ||
| "readOnly": true | ||
| }, | ||
| "operationFriendlyName": { | ||
ivanarandjelovic marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "description": "The friendly name of operation.", | ||
| "type": "string", | ||
| "readOnly": true | ||
| }, | ||
| "percentComplete": { | ||
ivanarandjelovic marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| "format": "int32", | ||
| "description": "The percentage of the operation completed.", | ||
| "type": "integer", | ||
| "readOnly": true | ||
| }, | ||
| "startTime": { | ||
| "format": "date-time", | ||
| "description": "The operation start time.", | ||
| "type": "string", | ||
| "readOnly": true | ||
| }, | ||
| "state": { | ||
|
There was a problem hiding this comment. Consider using provisioningState https://github.com/Azure/azure-resource-manager-rpc/blob/master/v1.0/async-api-reference.md#provisioningstate-property
Contributor
There was a problem hiding this comment. yeah, why not use existing definition ? |
||
| "description": "The operation state.", | ||
| "enum": [ | ||
| "Pending", | ||
| "InProgress", | ||
| "Succeeded", | ||
| "Failed", | ||
| "CancelInProgress", | ||
| "Cancelled" | ||
| ], | ||
| "type": "string", | ||
| "readOnly": true, | ||
| "x-ms-enum": { | ||
| "name": "ManagementOperationState", | ||
| "modelAsString": true | ||
| } | ||
| }, | ||
| "errorCode": { | ||
| "format": "int32", | ||
| "description": "The operation error code.", | ||
| "type": "integer", | ||
| "readOnly": true | ||
| }, | ||
| "errorDescription": { | ||
| "description": "The operation error description.", | ||
| "type": "string", | ||
| "readOnly": true | ||
| }, | ||
| "errorSeverity": { | ||
| "format": "int32", | ||
| "description": "The operation error severity.", | ||
| "type": "integer", | ||
| "readOnly": true | ||
| }, | ||
| "errorType": { | ||
| "description": "Error type (e.g. None, User).", | ||
| "enum": [ | ||
| "None", | ||
| "User" | ||
| ], | ||
| "type": "string", | ||
| "readOnly": true | ||
| }, | ||
|
Contributor
There was a problem hiding this comment. why are these needed in properties ? shouldn't they online come in error responses. and there is an error response definition in common-types
Contributor
There was a problem hiding this comment. Can you be more specific? |
||
| "estimatedCompletionTime": { | ||
| "format": "date-time", | ||
| "description": "The estimated completion time of the operation.", | ||
| "type": "string", | ||
| "readOnly": true | ||
| }, | ||
| "description": { | ||
| "description": "The operation description.", | ||
| "type": "string", | ||
| "readOnly": true | ||
| }, | ||
| "isCancellable": { | ||
| "description": "Whether the operation can be cancelled.", | ||
| "type": "boolean", | ||
|
Contributor
There was a problem hiding this comment. ARM recommends enums over booleans for future proof APIs. Standard guidance is: replace boolean/switch properties with a more meaningful enum whenever possible. A boolean will forever have two valid values (true or false). A string enum type is always preferred. Also, properties should always provide better values just than True and False. For example two switches "isTypeA" and "isTypeB" should be replaced with one enum "type": [A, B, DefaultType]. Enums are always a more flexible and future proof option because they allow additional values to be added in the future in a non-breaking way, e.g. [Enabled, Disabled, Suspended, Deallocated]. Note: do NOT define a 'boolean enum' with two values 'True and False'. This might be easier to 'extend' in terms of types, but semantically its cofusing, and no better than a boolean.
Contributor
There was a problem hiding this comment. Agree, I already changed errorType from boolean to enum. Can you suggest how to convert this to enum? It's a bit of a struggle to come up with property name that would have values "Cancelable", "NotCancelable". Maybe "CancelationType"? As this is also same as in SQL MI apis, and since Portal work is already done maybe we should leave it "as is" for now and change it in next API release. Would this be acceptable? |
||
| "readOnly": true | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "parameters": {}, | ||
| "securityDefinitions": { | ||
| "azure_auth": { | ||
| "type": "oauth2", | ||
| "description": "Azure Active Directory OAuth2 Flow", | ||
| "flow": "implicit", | ||
| "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", | ||
| "scopes": { | ||
| "user_impersonation": "impersonate your user account" | ||
| } | ||
| } | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,27 @@ | ||
| { | ||
| "parameters": { | ||
| "subscriptionId": "00000000-1111-2222-3333-444444444444", | ||
| "resourceGroupName": "resource-group", | ||
| "instancePoolName": "test-instance-pool", | ||
| "operationId": "c218773b-203f-4c7a-b174-6bd71fe20f72", | ||
| "api-version": "2024-05-01-preview" | ||
| }, | ||
| "responses": { | ||
| "200": { | ||
| "body": { | ||
| "properties": { | ||
| "instancePoolName": "test-instance-pool", | ||
| "operation": "UpsertInstancePoolAsync", | ||
| "operationFriendlyName": "UPDATE INSTANCE POOL", | ||
| "percentComplete": 100, | ||
| "startTime": "2024-04-22T14:46:00.423Z", | ||
| "state": "Succeeded", | ||
| "isCancellable": true | ||
| }, | ||
| "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/resource-group/providers/Microsoft.Sql/instancePools/test-instance-pool", | ||
| "name": "c218773b-203f-4c7a-b174-6bd71fe20f72", | ||
| "type": "Microsoft.Sql/instancePools/operations" | ||
| } | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| { | ||
| "parameters": { | ||
| "subscriptionId": "00000000-1111-2222-3333-444444444444", | ||
| "resourceGroupName": "resource-group", | ||
| "instancePoolName": "test-instance-pool", | ||
| "api-version": "2024-05-01-preview" | ||
| }, | ||
| "responses": { | ||
| "200": { | ||
| "body": { | ||
| "value": [ | ||
| { | ||
| "properties": { | ||
| "instancePoolName": "test-instance-pool", | ||
| "operation": "UpsertInstancePoolAsync", | ||
| "operationFriendlyName": "UPDATE INSTANCE POOL", | ||
| "percentComplete": 100, | ||
| "startTime": "2024-04-22T14:46:00.423Z", | ||
| "state": "Succeeded", | ||
| "isCancellable": true | ||
| }, | ||
| "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/resource-group/providers/Microsoft.Sql/instancePools/test-instance-pool", | ||
| "name": "c218773b-203f-4c7a-b174-6bd71fe20f72", | ||
| "type": "Microsoft.Sql/instancePools/operations" | ||
| }, | ||
| { | ||
| "properties": { | ||
| "instancePoolName": "test-instance-pool", | ||
| "operation": "UpsertInstancePoolAsync", | ||
| "operationFriendlyName": "UPDATE INSTANCE POOL", | ||
| "percentComplete": 100, | ||
| "startTime": "2024-04-22T14:46:22.847Z", | ||
| "state": "Succeeded", | ||
| "isCancellable": true | ||
| }, | ||
| "id": "/subscriptions/00000000-1111-2222-3333-444444444444/resourceGroups/resource-group/providers/Microsoft.Sql/instancePools/test-instance-pool", | ||
| "name": "b0326862-03dd-41a0-b239-5c3d7d68d098", | ||
| "type": "Microsoft.Sql/instancePools/operations" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,15 @@ | ||
| { | ||
| "parameters": { | ||
| "subscriptionId": "00000000-1111-2222-3333-444444444444", | ||
| "resourceGroupName": "resource-group", | ||
| "instancePoolName": "test-instance-pool", | ||
| "api-version": "2024-05-01-preview" | ||
| }, | ||
| "responses": { | ||
| "200": { | ||
| "body": { | ||
| "value": [] | ||
| } | ||
| } | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
use latest common-types