[Unified Vision Service ] API Review

[azure-sdk]

New API Review meeting has been requested.

Service Name: Unified Vision Service Review Created By: Kailash Joshi @kai-lash Review Date: 05/02/2023 01:00 PM PT PR: Hero Scenarios Link: Not Provided Core Concepts Doc Link: Not Provided

Description: Unified Vision Service Ingestion API for Image and Video Ingestion. This API is not ready yet (as of 4/10/23). Here is the design document for it: https://microsoft-my.sharepoint.com/:w:/p/tchuang/EdQXygVlEHdJoQdNsqdI38cBrgHlr0By0Zjc0VrlIA80cA?e=5aLASV I will put more details few days before the meeting as the implementation gets ready.

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]

@kai-lash have you submitted a PR for this API yet or will we only be reviewing the design document this time around? We can give feedback on the design document but we will need to see the PR before we can sign off.

[Kai-lash]

Hello @mikekistler, thanks for commenting. Here is the PR for this: https://github.com/Azure/azure-rest-api-specs-pr/pull/12181

[mikekistler]

@Kai-lash For data-plane APIs, we recommend using PRs in the public azure-rest-api-specs repo, rather than the private azure-rest-api-specs-pr repo, unless the API contains Microsoft confidential or business sensitive information. We are not asking you to move this PR, just to be aware of this recommendation and adopt this approach in the future.

[mikekistler]

@Kai-lash Microsoft has developed a new API design language called TypeSpec (formerly Cadl). TypeSpec and the TypeSpec Azure.Core library provide standard APIs patterns and constructs that promote compliance to Azure’s API Guidelines. The language is powerful and expressive, avoiding the “boilerplate” common in OpenAPI definitions. There is extensive tooling in VS and VSCode to improve productivity of API designers.
 


We are encouraging all Azure service teams to migrate to TypeSpec. All new services should either start with TypeSpec or migrate to TypeSpec as soon as possible. Services that do not have data plane SDKs today must migrate to TypeSpec to get SDKs.

Here are some resources to help you learn more about TypeSpec and how you can start using it for your service:
 

• TypeSpec Azure Docs: aka.ms/typespec/azure
• TypeSpec Azure Playground: aka.ms/trytypespec/azure
• TypeSpec Azure Process Docs: aka.ms/onboarding
• TypeSpec Discussion Teams channel: aka.ms/typespec/discussions

[mikekistler]

Notes from API Review meeting 5/2/23

• How does this service relate or integrate with Azure Cognitive Search?
• Can the ingestion simply take a Blob Storage container and ingest all documents in the container? That would be nice. Allow "Bring Your Own Storage" pattern.
• Why separate between images and videos? It might be nicer to have just one way to provide either.
• Or allow a single request to send both.
• Or ... if videos and images are separate resource types (can only search on one or the other), then the indexes should probably also be separate resources.
• Use "format: tag" on etag properties -- that will light up better in the generated SDKs
• What is the purpose of the model-version in the output?
• Interesting that the query operations are all POST. Should you have GET alternatives? At least for query by text?
• Filter - we recommend using OData expressions. That will be more consistent with other Azure services.
  • E.g. Search
• PUT (createIngestion) if long-running should return an Operation-Location header with the address of a status monitor to get the result
• Comments in this PR on the existing API do not need to be addressed for this preview, but should be addressed before it goes GA.

[Kai-lash]

Thanks for the notes, @mikekistler. Here is the response based on my discussion with the team.

• How does this service relate or integrate with Azure Cognitive Search?
• • From one of the recent discussions with SLT, we learned that the Cognitive search was not planning to cover image/multimedia at the point when we created the Search API for images.
• Can the ingestion simply take a Blob Storage container and ingest all documents in the container? That would be nice. Allow "Bring Your Own Storage" pattern.
• • This was one of our considerations. However, we decided against it because we wanted to support storage outside of Azure and allow the user to specify documents in a hybrid way (Azure, non-Azure, FileSystem, etc.)
• Why separate between images and videos? It might be nicer to have just one way to provide either.
• • Slight correction: images and videos could share the same index. Eventually, we want to provide the capability to support images and videos in the same request, although it may not be true now.
• Use "format: tag" on etag properties.
• • It tried adding "format": "tag", but it complained as being unrecognized. An existing example would help here.
• What is the purpose of the model-version in the output?
• • I have updated the input to include the model-version as well. So, consumers can set the model-version and see it back in the response to make sure their data is processed with the correct model version.
• Interesting that the query operations are all POST. Should you have GET alternatives?
• • This API will mostly be consumed by the other applications that may want to process the results further. Calling this API from the browser (with GET request) may not be suitable because of the payload requirement.
• Filter - we recommend using OData expressions.
• • Good suggestion. However, it was deemed a bit complex given the timeline we want to get this out. If possible, we might try it in the future.
• PUT (createIngestion) if long-running should return an Operation-Location header with the address of a status monitor to get the result
• • Fixed.

[mikekistler]

The subject PR was abandoned in favor of #23608