[Cognitive Services - Document Translator] REST API Review for Document Batch Translator API v1.1

[czubair]

Swagger PR: #16705

Service name: Document Batch Translator

Key contact for this review: alcheng;faanis

Are you in the PST time zone? If not, what time zone are you in? PST;Eastern European Time (Egypt = UTC+2)

Is this a new API or the first API for the service? No

Link to previous API version
https://github.com/Azure/azure-rest-api-specs/tree/main/specification/cognitiveservices/data-plane/TranslatorText/stable/v1.0

Has your service already been deployed?
No

Description of the material to be reviewed/changed:
https://microsoft-my.sharepoint.com/:w:/p/faanis/ES4dpXMEuc5IjGeTXMA6iwMBqstA6zvTV09h2XgZT8LI9A?e=gI8OiY

[markweitzel]

API Stewardship Meeting 1-Dec-21

The main motivation for adding this field is for discovery of the @failedDocumentStatus endpoint.

• Recommendation: Fixt the documentation first. This would avoid having to update this.
  • The examples in the quickstarts don't leverage the SDKs--shows raw code that don't show the pattern we'd like to promote.
• We should look at following the long running operations pattern more closely. Operation Location will have the status of the batch. Within that, there will be a status for each of the documents that are getting translated.

The standard pattern for "jump off to find the actual results for the LRO" is to have a resourceLocation attribute with the link. It would have the full set of results, though - whereas the current proposed failed results location filters on only the failed docs.

For the Word conversion API

• Consider restructuring this to have an extensible enum, with "WORD" and "NONE" as the only options. "NONE" would be the default. This will add a bit of "future proofing"
• The options for converting the document to word should be at the target level. This could also be done at the input/job level. You should make the call based on what they see their customers doing most so long as we could version in more flexibility over time.

Misc

• Add a default error. Try to follow the structure in the guidelines if possible.

References

• Document Translation Docs
• Recording link