api-guidelines
api-guidelines copied to clipboard
microsoft
[Azure REST API guidelines] Conflicting guidance on `status` values for resource-based LROs
The section Resource-based long-running operations states
✅ DO define the "status" field of the resource as an enum with all the values it may contain including the "terminal" values "Succeeded", "Failed", and "Canceled". See Enums & SDKs.
However, this doesn't seem to make much sense as succeeded|failed|canceled describe the status of the action on a resource but not the status of the resource itself.
The same section gives an example of setting status values as provisioning and active. These values describe the effect of the action on the state of resource, which is more logical.
A "create" operation (PUT, PATCH, or POST) for a resource where the basic structure of the resource is created immediately and includes a status field that indicates when the create has completed, e.g. "provisioning" -> "active".
A hypothetical other example can be POST /myThings/123:disable where a "status": "succeeded" on the myThing resource wouldn't communicate that myThing is now disabled.
