Skip to content
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

Cognitive Services URL template (endpoint) #3489

Closed
yangyuan opened this issue Jul 24, 2018 · 5 comments
Closed

Cognitive Services URL template (endpoint) #3489

yangyuan opened this issue Jul 24, 2018 · 5 comments
Labels
Cognitive - Mgmt Service Attention Workflow: This issue is responsible by Azure service team.

Comments

@yangyuan
Copy link
Member

yangyuan commented Jul 24, 2018

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
Copy link
Member Author

Computer Vision PR:
#3440
#3479

@yangyuan
Copy link
Member Author

Face PR:
#3490

@yangyuan
Copy link
Member Author

TextAnalytics PR:
#3491

@yangyuan
Copy link
Member Author

LUIS PR:
#3492

@yangyuan
Copy link
Member Author

Content Moderator PR:
#3505

@bsiegel bsiegel added the Service Attention Workflow: This issue is responsible by Azure service team. label Sep 26, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Cognitive - Mgmt Service Attention Workflow: This issue is responsible by Azure service team.
Projects
None yet
Development

No branches or pull requests

4 participants