Information and runtime behavior of the new design can be found at cadl-ranch PR
Major difference in PUT.
- Response of the PUT is the
Resource
object, not theOperationStatus
object. - The last GET on
Resource
URL preferred to be omitted. TheResource
object from the PUT is already the final result.
Major difference in POST.
- No
location
header in the response of POST as final resource URL, norresourceLocation
property inPollStatus
object. (new guideline discourage POST to create resource; POST should be used for action, not for create) - After POST, only status monitor API be accessed via GET. (as mentioned above, no
location
, noresourceLocation
to point to another URL) - Last
OperationStatus
object would haveresult
property when sucess, orerror
property when fail.
No difference in DELETE. LRO on PATCH discouraged.
PUT: PollerFlux<OperationStatus, Resource>
POST: PollerFlux<OperationStatus, Result>
The OperationStatus
contains id + status + error
properties.
The Result
from POST is extracted from the result
property of the last OperationStatus
from status monitor API.
Have a new subclass of OperationResourcePollingStrategy
, e.g. OperationLocationPollingStrategy
that dedicated to this new LRO design.
When emitter see that the LRO is from TypeSpec Azure.Core, use this OperationLocationPollingStrategy
in generated code.
If emitter see the LRO is from service TypeSpec, use existing DefaultPollingStrategy
.
Downside
- A new class in azure-core (first likely in azure-core-experimental)
- If DPG (Swagger) uses this new LRO, we'd need to add
polling
option to readme.md
It is hard to distinguish the design from the response of initialOperation (as the new design is designed to be mostly backward-compatible at REST API).
Hence, it could be difficult for OperationResourcePollingStrategy
, especially for the POST to extract result
property (it need to figure out that result
property exists, and the value can be converted to Result
class, which is a generic type).
Alternatively, we can add an option to existing OperationResourcePollingStrategy
, to let it know whether it handles new design. Then it would be very similar to behave as the aforementioned OperationLocationPollingStrategy
under this option.
It would be even harder to get DPG (Swagger) to configure this option.
Again, 1 or 2 new classes in azure-core (OperationStatus
and OperationState
; OperationState
is very similar to LongRunningOperationStatus
that exists, so we might able to use LongRunningOperationStatus
directly, via some hack in polling strategy).
Ref: TypeSpec models in Azure.Core.Foundations
However, I don't have good idea about what model we should use for polling result.
PollerFlux<BinaryData, Resource>
makes user hard to extract the error
(which by default is same model as ResponseError
, but can be specialized in Azure.Core).
PollerFlux<ResponseError, Resource>
makes the API hard to read, as in most cases, ResponseError
won't happen. Probably not PollerFlux<Optional<ResponseError>, Resource>
either.
Related PR in azure-core
getFinalResult
in PUT case, before polling complete.a. Add
id
anderror
toPollResponse
. But it may leave the poll result be empty (as PollerResponse has all the info)PollerFlux<Void, Resource>
.b. Add a e.g.
PollResult
class that containsid
anderror
.status
will not be included as it can be get from PollResponse.All new classes are first added to core-experimental.