Format of the State Object

[KirilKabakchiev]

State Object

All resources that support mutation operations (creation, deletion and update) MUST contain a state object. After performing a mutation request, the response MUST include a Location header from where information about the resource's state can be obtained. This MAY or MAY NOT be the Retrieve (GET) API for the resource entity that is being mutated.

The state reflects the real state in which the resource currently is. It includes information regarding whether the resource is currently usable or not (ready or not) and it contains conditions that provide further details if the resource is not ready (is not usable).

The state is of particular interest when the mutation operations are asynchronous. But even synchronously mutatable resources should provide state for consistency reasons. This state of synchronously mutated resources would often include no conditions.

Field	Type	Description
ready*	boolean	Indicates whether a resource is ready for use or not. This value is calculated by the Service Manager based on the conditions' statuses using a resource specific aggregation policy for the conditions that are defined for this resource
conditions*	array of conditions	Describe the state of the resource and indicate what actions should be taken in order for the resource to become ready. May be an empty array
message*	string	Human-readable summary for the reasoning behind the ready being what it is

Conditions Object

The conditions describe the current condition in which the resource is.
Each resource MAY add resource specific conditions and should also handle those conditions accordingly in case they sum up to an undesired state (in most cases this would be a ready:false state).
Each condition MAY include additional fields apart from those specified below in order to provide meaningful information.

Field	Type	Description
type*	string	The type of the condition. Each resource defines a set of condition types that are relevant for it.
status*	string	The status of the condition. Each condition defines its own status values and gives them semantics. Used to determine whether any actions should be taken in regards of this condition. For example, a condition of type last_operation with status in_progress would imply that the operation is still in running. If the status is success it would imply that the operation has successfully finished and if it is failed it would imply that the last_operation failed
message	string	Human-readable details that describe the condition

The state MUST be maintained up-to-date and reflect the real state of the resource. When a process or a component takes actions due to the state not matching what is actually desired, the process or component MUST also take care of updating the respective conditions that it has performed actions upon. When any conditions are updated the ready field MUST be recalculated and updated by the Service Manager.

Each Service Manager resource MUST define the conditions that are relevant for it. It MUST also define an aggregation policy that sums up the conditions and decides whether the resource is ready or not. Based on this policy every time a resource's condition is changed, the ready field should be recalculated and updated. The fact that each resource defines it's own conditions and an aggregation policy based on those conditions is an implementation detail but it is worth mentioning it here to better describe the idea behind the state.

Example Resource with a State Object:

{
  "id": "0941-12c4b6f2-335a-44a3-b971-424ec78c7353",
  ...
  "state": {  
    "ready": "False",
    "message": "Service Binding is currently being created",
    "conditions": [  
      {  
        "type": "last_operation",
        "status": "in_progress",
        "message": "Creating deployment pg-0941-12c4b6f2-335a-44a3-b971-424ec78c7353",
        "name": "Create"
      }
    ]
  }
}  

The example state above represents the state of a resource called service_binding with an id equal to 0941-12c4b6f2-335a-44a3-b971-424ec78c7353. The state implies that the service binding is not ready (it is not usable) due to the fact that the last operation (namely Create, hence the name field) performed on this entity is currently still running (the status of the last_operation condition is in_progress).