microsoft / microsoft/api-guidelines
Error details for stepwise long-running operations
Nobody has claimed this yet.
- Dominant language
- No language data
- Stars
- 23.3k
- Forks
- 2.7k
- PR merge metrics
- No merged PRs in 30d
Description
Services MUST perform as much synchronous validation as practical on stepwise requests. Services MUST prioritize returning errors in a synchronous way, with the goal of having only "Valid" operations processed using the long running operation wire protocol.
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
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read the stepwise request guidance and the OData-style error condition section in Guidelines.md, then compare them with the linked Azure Cognitive Services example. Define whether and how error details should be exposed for failed long-running operations, and document the resulting guidance in the API guidelines.
Written by the indexing model from the issue text.
Assessment
- Domain
- api, documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100