[DataMap ] API Review

[azure-sdk]

New API Review meeting has been requested.

Service Name: DataMap Review Created By: Yifan Zhou Review Date: 11/30/2023 04:00 PM PT Onboarding Record: PR: Hero Scenarios Link: Not Provided Core Concepts Doc Link: Not Provided

Description:

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

[azure-sdk]

Meeting updated by Yifan Zhou

Service Name: DataMap Review Created By: Yifan Zhou Review Date: 11/30/2023 04:00 PM PT Onboarding Record: PR: https://github.com/Azure/azure-rest-api-specs/pull/26335/files Hero Scenarios Link: Not Provided Core Concepts Doc Link: Not Provided

Description:

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

[azure-sdk]

Meeting updated by Yifan Zhou

Service Name: DataMap Review Created By: Yifan Zhou Review Date: 11/30/2023 04:00 PM PT Onboarding Record: PR: https://github.com/Azure/azure-rest-api-specs/pull/26335/files Hero Scenarios Link: Not Provided Core Concepts Doc Link: Not Provided

Description:

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

[azure-sdk]

Meeting updated by Yifan Zhou

Service Name: DataMap Review Created By: Yifan Zhou Review Date: 11/30/2023 04:00 PM PT Onboarding Record: PR: https://github.com/Azure/azure-rest-api-specs/pull/26335/files Hero Scenarios Link: Not Provided Core Concepts Doc Link: Not Provided

Description:

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

[heaths]

Review feedback:

• Refer to a Key Vault secret name by its URL e.g., https://{vault-name}.vault.azure.net/secrets/{secret-name}
• Key Vault service doesn't recommend SAS tokens be generated from Key Vault anymore. Recommendation is to use Managed Identity. You should talk with Jack Lichwa about this.
• If you need to support SAS tokens, have customers pass the blob container URI with the SAS token query string. This is how most services work that need to support SAS tokens for "bring your own storage". See https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#bring-your-own-storage-byos
• Canceling an LRO should use {endpoint}/{collection}:cancel or {endpoint}/{collection}/{resource}:cancel. See https://github.com/microsoft/api-guidelines/blob/vNext/azure/ConsiderationsForServiceDesign.md#controlling-a-long-running-operation and https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#performing-an-action for general POST action guidelines.
• Entity_ListOperationStatus should be a usual pageable, not return array: https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#collections-response-is-object
• Use the ?enableLiveMode=bool query parameter for your live mode feature, per discussion. Option 2 is not RESTful and doubles your associated endpoints.
• Listing and browsing assets should use pageable GETs e.g.,

  GET /browse?path=/ -> {"value":["dir1","dir2"]}
  GET /browse?path=/dir1

  Our SDKs don't support pageable POSTs. If you keep it as a POST because of the number of parameters, there will be no SDK support. Users will have to construct and send requests with a continuation token each time.

• Remove the count request property from your browse endpoint.
• top should be maxpagesize for the browse endpoint.
• Both maxpagesize and continuationToken should be moved to query parameters. With a pageable POST, at least this would make it easier on customers to send the same request body but vary the 2 things that should vary.
• Return the absolute path in the browse response so the user doesn't have to canonicalize themselves, which has no SDK support and makes the API harder to use. You already know it, so it's just as easy for the service to do consistently.
• For the chat/copilot functionality, we recommend looking at existing services that have done this so we have a consistent experience for all Copilots across Azure e.g., DocumentIntelligence (/cc @bojunehsu).
  • Actually, probably mimic the Azure OpenAI API since you're trying to do something similar. They also support streaming mode as well, so you shouldn't reinvent your own way.
  • To see SDK support, in whatever language you want, search for Azure OpenAI SDK in the respective package manager e.g., nuget.org for .NET.
  • Contact @richardpark-msft for the Go SDK
• POSTing to the same endpoint with an op parameter is not RESTful and would not be supported by the SDKs. Separate schemas should have separate endpoints.
• Rename skillType to just skill for the skill endpoint.