[Cognitive Services Computer Vision API ] API Review

[azure-sdk]

New API Review meeting has been requested.

Service Name: Cognitive Services Computer Vision API Review Created By: Kailash Joshi Review Date: 10/24/2023 01:00 PM PT Onboarding Record: PR: Hero Scenarios Link: Not Provided Core Concepts Doc Link: Not Provided

Description: API review for ImageAnalysis API for GA

Detailed meeting information and documents provided can be accessed here For more information that will help prepare you for this review, the requirements, and office hours, visit the documentation here

[Kai-lash]

API Spec PR link: https://github.com/Azure/azure-rest-api-specs-pr/pull/15240

[azure-sdk]

Meeting updated by Kailash Joshi

Service Name: Cognitive Services Computer Vision API Review Created By: Kailash Joshi Review Date: 10/24/2023 01:00 PM PT Onboarding Record: PR: Hero Scenarios Link: Not Provided Core Concepts Doc Link: Not Provided

Description: API review for ImageAnalysis API for GA API Spec PR link: Azure/azure-rest-api-specs-pr#15240

Detailed meeting information and documents provided can be accessed here For more information that will help prepare you for this review, the requirements, and office hours, visit the documentation here

[mikekistler]

Notes from API Review Meeting 10/24/23

• The SDKs will be generated from TypeSpec. We really want to review the TypeSpec.
  • TypeSpec files were not created by the service team
  • TypeSpec review will be done as part of SDK review.

Previous feedback:

• https://github.com/Azure/azure-rest-api-specs-pr/issues/7432#issuecomment-1151727918

• No more operations in the path -- good

• Long running operation ? No, it is synchronous

• Body content types missing because the OpenAPI uses x-ms-paths

• Why are some fields sent in the parameters and others in the body?

  • To make the API the same regardless of content type (request body could be the raw image)

• Should we use "confidence", "confidenceScore", "score"?

  • We should make sure we are using the best terminology

• Bounding box is in pixels ... good. We should make sure it is pixels everywhere.

• "TagsResult.values" seems a little verbose ... could it be "Tags.values" ?

  • Everything in this model is a result ... does it have to be in the name?

• Why are we using kebab case rather than camelCase for query parameter names?

  • We should make this clearer in our REST API guidelines.

• All the features and results but Read are nouns, and that one is a verb.

  • No strong opinion here.

This looks good for GA. Please consider the above and any comments on the PR, then tag us here when you are ready to merge and we'll add the "signedOff" label.