diff --git a/spec.md b/spec.md index 2bcef6d6..a8892bff 100644 --- a/spec.md +++ b/spec.md @@ -328,6 +328,9 @@ For error responses, the following fields are defined: | --- | --- | --- | | error | string | A single word in camel case that uniquely identifies the error condition. If present, MUST be a non-empty string. | | description | string | A user-facing error message explaining why the request failed. If present, MUST be a non-empty string. | +| instance_usable | boolean | If an update or deprovisioning operation failed, this flag indicates whether or not the Service Instance is still usable. If `true`, the Service Instance can still be used, `false` otherwise. This field MUST NOT be present for errors of other operations. Defaults to true. | +| update_repeatable | boolean | If an update operation failed, this flag indicates whether this update can be repeated or not. If `true`, the same update operation MAY be repeated and MAY succeed; if `false`, repeating the same update operation will fail again. This field MUST NOT be present for errors of other operations. Defaults to true. | +| retry_after | integer | This field suggests how long (in seconds) the Platform SHOULD wait until it repeats the operation. If this a negative number, the Platform SHOULD NOT automatically repeat the operation. Defaults to 0 seconds. | ### Error Codes @@ -772,7 +775,12 @@ For success responses, the following fields are defined: | Response Field | Type | Description | | --- | --- | --- | | state* | string | Valid values are `in progress`, `succeeded`, and `failed`. While `"state": "in progress"`, the Platform SHOULD continue polling. A response with `"state": "succeeded"` or `"state": "failed"` MUST cause the Platform to cease polling. | -| description | string | A user-facing message that can be used to tell the user details about the status of the operation. | +| description | string | A user-facing message that can be used to tell the user details about the status of the operation. If present, MUST be a non-empty string. | +| instance_usable | boolean | If an update or deprovisioning operation failed, this flag indicates whether or not the Service Instance is still usable. If `true`, the Service Instance can still be used, `false` otherwise. This field MUST NOT be present for errors of other operations. Defaults to true. | +| update_repeatable | boolean | If an update operation failed, this flag indicates whether this update can be repeated or not. If `true`, the same update operation MAY be repeated and MAY succeed; if `false`, repeating the same update operation will fail again. This field MUST NOT be present for errors of other operations. Defaults to true. | +| retry_after | integer | If an operation failed, this field suggests how long (in seconds) the Platform SHOULD wait until it repeats the operation. If this a negative number, the Platform SHOULD NOT automatically repeat the operation. Defaults to 0 seconds. | + +\* Fields with an asterisk are REQUIRED. The response MAY also include the `Retry-After` HTTP header. This header will indicate how long the Platform SHOULD wait before polling again and is @@ -780,7 +788,7 @@ intended to prevent unnecessary, and premature, calls to the `last_operation` endpoint. It is RECOMMENDED that the header include a duration rather than a timestamp. -\* Fields with an asterisk are REQUIRED. + ``` { @@ -1179,6 +1187,36 @@ Responses with any other status code MUST be interpreted as a failure. When the response includes a 4xx status code, the Service Broker MUST NOT apply any of the requested changes to the Service Instance. +When an update fails, the Service Instance can still be usable or unusable +or its state could be unknown to the Platform. If a Service Instance became +unusable, another update MAY repair the Service Instance. +The Platform SHOULD NOT allow the creation of new bindings of an unusable +Service Instance until the instance has been deleted or repaired by a +subsequent update. +If the broker does not indicate in the +[Error response](#service-broker-errors) or +[Last Operation response](#polling-last-operation-for-service-instances) +whether the Service Instance is usable or not, the Platform SHOULD assume +it is still usable. + +A failed update might be repeatable. If the Service Broker +indicates in the [Error response](#service-broker-errors) or +[Last Operation response](#polling-last-operation-for-service-instances) +that retrying this update does not make sense, the Platform SHOULD NOT +repeat this update. +For example, if a certain plan change is not supported by the +Service Broker, all subsequent attempts will always fail, and the +Platform SHOULD NOT retry this. +Other updates MAY be possible. + +If an update is repeatable, the Service Broker MAY indicate whether +the update is repeatable immediately, after a certain period of time, +or after some manual intervention. If the Service Broker does not provide +this information, the Platform SHOULD assume that the update can be +repeated immediately. +Whether the Platform automatically repeats the update or not, is Platform +specific. + #### Body For success responses, the following fields are defined: @@ -1635,6 +1673,14 @@ $ curl 'http://username:password@service-broker-url/v2/service_instances/:instan Responses with any other status code MUST be interpreted as a failure and the Platform MUST remember the Service Instance. +When a deprovisioning fails, the Service Instance can still be usable or +unusable or its state could be unknown. If a Service Instance became unusable, +the Platform SHOULD NOT allow the creation of new bindings. +If the broker does not indicate in the [Error response](#service-broker-errors) +or [Last Operation response](#polling-last-operation-for-service-instances) +whether the Service Instance is usable or not, the Platform SHOULD assume it is +still usable. + #### Body For success responses, the following fields are defined: