Open letmaik opened 3 years ago
While the general guidelines are silent about it, the Azure guidelines are more prescriptive: https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#obtaining-status-and-results-of-long-running-operations. It may be worth recommending to use the "error"
field in the general guidelines as well.
DO return a status monitor in the response body that conforms with the following structure:
OperationStatus : Object
Property | Type | Required | Description |
---|---|---|---|
id |
string | true | The unique id of the operation |
status |
string | true | enum that includes values "NotStarted", "Running", "Succeeded", "Failed", and "Canceled" |
error |
ErrorDetail | Error object that describes the error when status is "Failed" | |
result |
object | Only for POST action-type LRO, the results of the operation when completed successfully | |
additional properties |
Additional named or dynamic properties of the operation |
How should error details be exposed for operation failures? The guidelines are silent about that, whereas I would have expected that an OData-style
"error"
field should be included in the response.I similarly can't see how real APIs deal with that which seems extremely odd: https://docs.microsoft.com/en-us/azure/cognitive-services/computer-vision/concept-recognizing-text