Closed letmaik closed 3 years ago
Owing to the immutable nature of the ledger, historical queries are always pure reads on constant inputs. The results themselves are not transient, only their caching in memory is.
Creating a specific resource location every time they are queried isn’t helpful, and the LRO flow adds an extra two unnecessary requests compared to the sample flow. It also complicates the server-side implementation by making it stateful.
Since CCF is a replicated system, that state must be propagated, which introduces further latency and opportunity for failure. By comparison, CCF’s sample implementation is impervious to nodes crashing or rolling back. It necessitates no additional logic on the client or on the server side to handle these situations.
Although historical query flow implementation is ultimately up to the application, we recommend implementing the more efficient and robust flow illustrated in the sample.
Part of https://github.com/microsoft/CCF/issues/1918. Related to https://github.com/microsoft/CCF/issues/1705.
https://github.com/microsoft/api-guidelines/blob/vNext/Guidelines.md#132-stepwise-long-running-operations
Currently, historical endpoints either return the final response or a
202 Accepted
withRetry-After
header.The Microsoft REST API guidelines say it should go like that:
202 Accepted
back together withOperation-Location
header and optionallyRetry-After
Operation-Location
200 OK
with"status": "running"
and optionallyRetry-After
header200 OK
with"status": "succeeded"
and"resourceLocation": "https://...
to fetch the result200 OK
with"status": "failed"
. The guide doesn't say how error details are communicated. They do say that error conditions should be checked in the initial request as much as possible:Example: https://docs.microsoft.com/en-us/azure/cognitive-services/computer-vision/concept-recognizing-text
The main difference to the current approach is that CCF would be in charge to call the historical endpoint and store the result somewhere. The client would call the "operation"-interface of the historical endpoint which always creates an operation, even if the result would be available already.
Note that specific details and extensions (like requesting responses for a range of txs) are orthogonal to the above and wouldn't change the general operation interface.