Cognitive Services URL template (endpoint)

[yangyuan]

Creating this issue for PRs.

Background:

1. Cognitive Services used to use "https://[region].api.cognitive.microsoft.com" as URL template, but the template will no longer be flexible to fulfill the requirements. The hostname can be any domain and the protocol could be HTTP.
2. The auto-generated API Reference has "Try It" feature, (for example: Face - Find Similar). We want it to be available for Cognitive Services APIs.

Final Design:

Swagger:

"x-ms-parameterized-host": {
  "hostTemplate": "{Endpoint}/face/v1.0",
  "useSchemePrefix": false,
  "parameters": [
    {
      "$ref": "#/parameters/Endpoint"
    }
  ]
}

"parameters": {
  "Endpoint": {
    "name": "Endpoint",
    "description": "Supported Cognitive Services endpoints (protocol and hostname, for example: https://westus.api.cognitive.microsoft.com).",
    "x-ms-parameter-location": "client",
    "required": true,
    "type": "string",
    "in": "path",
    "x-ms-skip-url-encoding": true
  }
}

C# Client:

new FaceClient(...) {
    Endpoint = "https://westus.api.cognitive.microsoft.com"
};

FAQ

Where to find the "Endpoint".

Endpoint is the terminology we've been used for years. You can find the "Endpoint" on the Azure Portal resource. We will try to provide consistent Endpoint format among Cognitive Services. We will also try to ensure developers can directly copy the Endpoint without modification.

Why "Endpoint" is a "$ref" parameter.

If we put "Endpoint" definition in x-ms-parameterized-host.parameters, autorest will treat the Endpoint parameter as "x-ms-parameter-location": "method". Not confirmed but this is probably a bug. When the issue get fixed, we can put "Endpoint" back to x-ms-parameterized-host.parameters. No SDK update required.

Why "Endpoint" doesn't contain "/face/v1.0".

A couple of reasons:

1. Compatibility with swagger 2.0, autorest only support swagger 2.0. Swagger 2.0 use "host+basePath+scheme", and when basePath exists, autorest will append basePath to the tail of x-ms-parameterized-host. So to make it possible to support both autorest and other tools, x-ms-parameterized-host can only contain scheme and host.
2. Few APIs are not following the common base path format.
3. We will able to provide pre-defined string enums for common endpoints.
4. Decouple version and client. (Client might support multiple versions when really necessary)

History Changes:

Some of the SDKs changed to below before change to final design.

"host": "api.cognitive.microsoft.com",
"basePath": "/face/v1.0",
"schemes": [
  "https"
],

This is because:

1. We didn't notice the "Try It" feature in API Reference.
2. The issue (probably bug) mentioned in FAQ.

This design has a flaw that if user forgot to set endpoint, they will get 404 (which is not perfect). The new design, they will get an error "Endpoint should not be null". As we've found a workaround (use $ref), I think its better to switch to the new design.

[yangyuan]

Computer Vision PR: https://github.com/Azure/azure-rest-api-specs/pull/3440 https://github.com/Azure/azure-rest-api-specs/pull/3479

[yangyuan]

Face PR: https://github.com/Azure/azure-rest-api-specs/pull/3490

[yangyuan]

TextAnalytics PR: https://github.com/Azure/azure-rest-api-specs/pull/3491

[yangyuan]

LUIS PR: https://github.com/Azure/azure-rest-api-specs/pull/3492

[yangyuan]

Content Moderator PR: https://github.com/Azure/azure-rest-api-specs/pull/3505