[Cognitive Services - Language - Authoring API] <2022-10-01-preview>

[peytonfraser]

Service name: Azure Cognitive Service for Language Key contacts for the review:

• PM: Peyton Fraser [email protected]
• Authoring Engineering Lead: Hadeer Magdy [email protected]
• [CT] Custom Summarization: Amir George [email protected]
• [CT] OOS Amir George [email protected]
• [QnA] CQA Project Versioning Victor Das [email protected]
• [CLU] Versioning Amir George [email protected]
• [CT] Versioning Amir George [email protected]
• Multi region deployment Amir George [email protected]

Whether this is a new or existing API: Existing API Whether or not your service already been deployed: Yes A brief description of the material to be reviewed/changed: We are adding new features for the October API, including [CT] Custom Summarization, [CT] OOS, [QnA] CQA Project Versioning, [CLU] Versioning, [CT] Versioning, and Multi region deployment.

[AmirGeorge]

CLU authoring swagger: https://msazure.visualstudio.com/Cognitive%20Services/_git/API-Language-Authoring?path=/UnifiedAuthoring.APIs/Swagger/Microsoft.ConversationalLanguageUnderstanding.Authoring.v2022-10-01-preview.json

CLU diff from previous API version: https://msazure.visualstudio.com/Cognitive%20Services/_git/API-Language-Authoring/pullrequest/6640395?_a=files&path=/UnifiedAuthoring.APIs/Swagger/Microsoft.ConversationalLanguageUnderstanding.Authoring.v2022-05-01.json

Custom Text authoring swagger: https://msazure.visualstudio.com/Cognitive%20Services/_git/API-Language-Authoring?path=/UnifiedAuthoring.APIs/Swagger/Microsoft.CustomText.Authoring.v2022-10-01-preview.json

Custom Text diff from previous API version: https://msazure.visualstudio.com/Cognitive%20Services/_git/API-Language-Authoring/pullrequest/6640395?_a=files&path=/UnifiedAuthoring.APIs/Swagger/Microsoft.CustomText.Authoring.v2022-05-01.json

[peytonfraser]

@markweitzel please see Amir's PRs linked above.

[markweitzel]

https://msazure.visualstudio.com/Cognitive%20Services/_git/API-Language-Authoring?path=/UnifiedAuthoring.APIs/Swagger/Microsoft.CustomText.Authoring.v2022-10-01-preview.json

@peytonfraser -- Because these changes will flow downstream into the SDK process, we use github PRs--not AZDO--as the source of truth for API reviews. @AmirGeorge -- would you please create a PR in github?

[AmirGeorge]

GitHub PR https://github.com/Azure/azure-rest-api-specs/pull/20347

[markweitzel]

API Stewardship Board Review: 23-Aug-22

• Recommended: CustomAbstractiveSummarization --> CustomAbstractSummarization...

• Document the TTL for the regex. Customers will need to know how long this can run for.

• regex expressions reads well enough. You could consider things like cases, options, matchers, conditions, etc., if you're trying to avoid the repetition.

Consider making expressions a map (see below). The map is also more PATCH-able, if this API is so inclined.

"expressions": {
  "UK Phone Numbers": {
    "language": "en",
    "pattern": "/.../" }}

• Note Language follows the latest action pattern with /:

• Be careful with naming, especially around versioning and snapshots.

Next Steps

• We did not finish the review--need to continue the discussion and finish the remaining.

References

Meeting Recording & Chat

[markweitzel]

API Stewardship Board Review 31-Aug-22

Reviewing part of the API we did not get to on Aug 23.

Please be sure to use "format": "arm-id" per https://github.com/Azure/autorest/blob/main/packages/libs/openapi/src/v3/formats.ts#L55 for the values in that resourceIds array so they're generated as https://docs.microsoft.com/en-us/dotnet/api/azure.core.resourceidentifier?view=azure-dotnet in languages with fancy types.

• Should this be x-ms-authorization-auxiliary in ARM if it's the same concept
• Is there a way to remove the armToken - could a service principal be used instead?
  • Talk with Scott Schalb. Also connect with the ARM team (Roopesh Manda)
  • How will the token be acquired, managed, secured, etc...

There is a possibility of creating an "unreachable" / "orphaned" resources in the current process. Three possible scenarios:

• Linked & locked
• Cascade delete
• Dangling links For the "delete & recreate with the same name scenario" -- make sure the error message is very clear what happened.

PUT is a create or replace. PATCHing an array is problematic. This should be a POST and follow the "Performing an Action" pattern.

DELETE - Create a POST action for this eg unassign A payload within a DELETE request message has no defined semantics; sending a payload body on a DELETE request might cause some existing implementations to reject the request.

References

Meeting Chat Meeting Recording