-
Notifications
You must be signed in to change notification settings - Fork 5.6k
Add specs for Available Service Aliases #7362
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
sergey-shandar
merged 1 commit into
Azure:master
from
anton-evseev:available-service-aliases
Oct 2, 2019
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
159 changes: 159 additions & 0 deletions
159
...network/resource-manager/Microsoft.Network/stable/2019-08-01/availableServiceAliases.json
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,159 @@ | ||
| { | ||
| "swagger": "2.0", | ||
| "info": { | ||
| "title": "NetworkManagementClient", | ||
| "description": "The Microsoft Azure Network management API provides a RESTful set of web services that interact with Microsoft Azure Networks service to manage your network resources. The API has entities that capture the relationship between an end user and the Microsoft Azure Networks service.", | ||
| "version": "2019-08-01" | ||
| }, | ||
| "host": "management.azure.com", | ||
| "schemes": [ | ||
| "https" | ||
| ], | ||
| "consumes": [ | ||
| "application/json" | ||
| ], | ||
| "produces": [ | ||
| "application/json" | ||
| ], | ||
| "security": [ | ||
| { | ||
| "azure_auth": [ | ||
| "user_impersonation" | ||
| ] | ||
| } | ||
| ], | ||
| "securityDefinitions": { | ||
| "azure_auth": { | ||
| "type": "oauth2", | ||
| "authorizationUrl": "https://login.microsoftonline.com/common/oauth2/authorize", | ||
| "flow": "implicit", | ||
| "description": "Azure Active Directory OAuth2 Flow.", | ||
| "scopes": { | ||
| "user_impersonation": "impersonate your user account" | ||
| } | ||
| } | ||
| }, | ||
| "paths": { | ||
| "/subscriptions/{subscriptionId}/providers/Microsoft.Network/locations/{location}/availableServiceAliases": { | ||
| "get": { | ||
| "operationId": "AvailableServiceAliases_List", | ||
| "description": "Gets all available service aliases for this subscription in this region.", | ||
| "parameters": [ | ||
| { | ||
| "name": "location", | ||
| "in": "path", | ||
| "required": true, | ||
| "type": "string", | ||
| "description": "The location." | ||
| }, | ||
| { | ||
| "$ref": "./network.json#/parameters/SubscriptionIdParameter" | ||
| }, | ||
| { | ||
| "$ref": "./network.json#/parameters/ApiVersionParameter" | ||
| } | ||
| ], | ||
| "responses": { | ||
| "200": { | ||
| "description": "Request successful. Returns all available service aliases for the subscription in the region.", | ||
| "schema": { | ||
| "$ref": "#/definitions/AvailableServiceAliasesResult" | ||
| } | ||
| } | ||
| }, | ||
| "x-ms-examples": { | ||
| "Get available service aliases": { | ||
| "$ref": "./examples/AvailableServiceAliasesList.json" | ||
| } | ||
| }, | ||
| "x-ms-pageable": { | ||
| "nextLinkName": "nextLink" | ||
| } | ||
| } | ||
| }, | ||
| "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Network/locations/{location}/availableServiceAliases": { | ||
| "get": { | ||
| "operationId": "AvailableServiceAliases_ListByResourceGroup", | ||
| "description": "Gets all available service aliases for this resource group in this region.", | ||
| "parameters": [ | ||
| { | ||
| "name": "resourceGroupName", | ||
| "in": "path", | ||
| "required": true, | ||
| "type": "string", | ||
| "description": "The name of the resource group." | ||
| }, | ||
| { | ||
| "name": "location", | ||
| "in": "path", | ||
| "required": true, | ||
| "type": "string", | ||
| "description": "The location." | ||
| }, | ||
| { | ||
| "$ref": "./network.json#/parameters/SubscriptionIdParameter" | ||
| }, | ||
| { | ||
| "$ref": "./network.json#/parameters/ApiVersionParameter" | ||
| } | ||
| ], | ||
| "responses": { | ||
| "200": { | ||
| "description": "Request successful. Returns all available service aliases for the resource group in the region.", | ||
| "schema": { | ||
| "$ref": "#/definitions/AvailableServiceAliasesResult" | ||
| } | ||
| } | ||
| }, | ||
| "x-ms-examples": { | ||
| "Get available service aliases in the resource group": { | ||
| "$ref": "./examples/AvailableServiceAliasesListByResourceGroup.json" | ||
| } | ||
| }, | ||
| "x-ms-pageable": { | ||
| "nextLinkName": "nextLink" | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "definitions": { | ||
| "AvailableServiceAlias": { | ||
| "properties": { | ||
| "name": { | ||
| "type": "string", | ||
| "description": "The name of the service alias." | ||
| }, | ||
| "id": { | ||
| "type": "string", | ||
| "description": "The ID of the service alias." | ||
| }, | ||
| "type": { | ||
| "type": "string", | ||
| "description": "The type of the resource." | ||
| }, | ||
| "resourceName": { | ||
| "type": "string", | ||
| "description": "The resource name of the service alias." | ||
| } | ||
| }, | ||
| "description": "The available service alias." | ||
| }, | ||
| "AvailableServiceAliasesResult": { | ||
| "properties": { | ||
| "value": { | ||
| "type": "array", | ||
| "items": { | ||
| "$ref": "#/definitions/AvailableServiceAlias" | ||
| }, | ||
| "description": "An array of available service aliases." | ||
| }, | ||
| "nextLink": { | ||
| "readOnly": true, | ||
| "type": "string", | ||
| "description": "The URL to get the next set of results." | ||
| } | ||
| }, | ||
| "description": "An array of available service aliases." | ||
| } | ||
| } | ||
| } | ||
27 changes: 27 additions & 0 deletions
27
...rce-manager/Microsoft.Network/stable/2019-08-01/examples/AvailableServiceAliasesList.json
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": { | ||
| "api-version": "2019-08-01", | ||
| "location": "westcentralus", | ||
| "subscriptionId": "subId" | ||
| }, | ||
| "responses": { | ||
| "200": { | ||
| "body": { | ||
| "value": [ | ||
| { | ||
| "name": "servicesAzure", | ||
| "id": "/subscriptions/subId/providers/Microsoft.Network/AvailableServiceAliases/servicesAzure", | ||
| "type": "Microsoft.Network/AvailableServiceAliases", | ||
| "resourceName": "/services/Azure" | ||
| }, | ||
| { | ||
| "name": "servicesAzureManagedInstance", | ||
| "id": "/subscriptions/subId/providers/Microsoft.Network/AvailableServiceAliases/servicesAzureManagedInstance", | ||
| "type": "Microsoft.Network/AvailableServiceAliases", | ||
| "resourceName": "/services/Azure/ManagedInstance" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| } | ||
| } |
28 changes: 28 additions & 0 deletions
28
...rosoft.Network/stable/2019-08-01/examples/AvailableServiceAliasesListByResourceGroup.json
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,28 @@ | ||
| { | ||
| "parameters": { | ||
| "api-version": "2019-08-01", | ||
| "location": "westcentralus", | ||
| "subscriptionId": "subId", | ||
| "resourceGroupName": "rg1" | ||
| }, | ||
| "responses": { | ||
| "200": { | ||
| "body": { | ||
| "value": [ | ||
| { | ||
| "name": "servicesAzure", | ||
| "id": "/subscriptions/subId/providers/Microsoft.Network/AvailableServiceAliases/servicesAzure", | ||
| "type": "Microsoft.Network/AvailableServiceAliases", | ||
| "resourceName": "/services/Azure" | ||
| }, | ||
| { | ||
| "name": "servicesAzureManagedInstance", | ||
| "id": "/subscriptions/subId/providers/Microsoft.Network/AvailableServiceAliases/servicesAzureManagedInstance", | ||
| "type": "Microsoft.Network/AvailableServiceAliases", | ||
| "resourceName": "/services/Azure/ManagedInstance" | ||
| } | ||
| ] | ||
| } | ||
| } | ||
| } | ||
| } |
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.
All fields beyond id, name, type should be inside a 'properties' envelope.
How is resourceName different than name? is there a more descriptive field name you could pick which is self describing?
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.
This isn't azure resource but service alias data. Not sure if that should adhere to resource's conventions of nesting properties.
Resource name is fully-qualified name like
/services/Azure/ManagedInstancewhen name is just resource name without slashes (e.g.servicesAzureManagedInstance)@avijitgupta should be able to provide more information
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.
Not looking at the name or content of the request, only at the format. This is a Get request on a URL which should be an azure resource. When we do this, it should follow the convention of an azure resource.
"/services/Azure/ManagedInstance" isn't a azure resource name, so it will cause some confusion. Is there a different name we can call it?
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.
@ryansbenson
Below is the logic on the server.
this.Name = resourceName.Replace("/", string.Empty);
this.ResourceName = resourceName;
this.Id = string.Format("/subscriptions/{0}/resourceGroup/{1}/providers/Microsoft.Network/AvailableServiceAliases/{2}", subscriptionId, groupName, this.Name);
this.Type = "Microsoft.Network/AvailableServiceAliases";
Name is the azure resource name which does not have any '/' (it follows the ceonvention of azure resource)
ResourceName is another property which is the alias which the customer is expected to use. Don't expect it to cause confusion.
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.
@ryansbenson one extra thing - this API is already live so we can't change property names or object structure
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.
@avijitgupta - With no change, when a user is told to "Use the resource name to ___", both could be valid interpretations. Why don't you call it "ResourceAlias"? Also, the Id should also include the /location/{location}/ part of the path (the ID should be Get-able).
@number213 - Your RP manifest doesn't have a route for locations/availableServiceAliases yet, so there can't be production traffic going to this path in your service. These reviews are in place to force consistency and catch issues like this before they go live.
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.
There is precedence set with other network APIs with properties outside of the properties body. Though this isn't compliant and will cause issues across ARM tooling, this is understood by the network team.
With regard to resourceName being confusing - it was agreed that a new name, something like 'alias' or 'resourceAlias', should be used but will be changed in a future API version.