Expose historical query endpoints as long-running operations following Microsoft guidelines

[letmaik]

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 with Retry-After header.

The Microsoft REST API guidelines say it should go like that:

• Get 202 Accepted back together with Operation-Location header and optionally Retry-After
• Client waits and fetches URL from Operation-Location
  • If result not ready: 200 OK with "status": "running" and optionally Retry-After header
  • If result ready: 200 OK with "status": "succeeded" and "resourceLocation": "https://... to fetch the result
  • If error: 200 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:

    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.

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.

For an API that's defined as a Stepwise Long Running Operation the service MUST go through the Stepwise Long Running Operation flow even if the operation can be completed immediately. In other words, APIs must adopt and stick with an LRO pattern and not change patterns based on circumstance.

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.

[achamayou]

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.