diff --git a/openapi.yaml b/openapi.yaml index 4309a0b6..72e09e5c 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -757,6 +757,10 @@ components: - failed description: type: string + instance_usable: + type: boolean + update_repeatable: + type: boolean ServiceBindingResource: type: object @@ -898,6 +902,10 @@ components: type: string description: type: string + instance_usable: + type: boolean + update_repeatable: + type: boolean securitySchemes: basicAuth: diff --git a/spec.md b/spec.md index 2fe7a3a8..0985a3b7 100644 --- a/spec.md +++ b/spec.md @@ -350,6 +350,8 @@ 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`. | ### Error Codes @@ -805,7 +807,9 @@ 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`. | 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 @@ -1232,6 +1236,28 @@ 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. + #### Body For success responses, the following fields are defined: @@ -1734,6 +1760,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 becomes unusable, +the Platform SHOULD NOT request new Service Bindings for that Service Instance. +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: diff --git a/swagger.yaml b/swagger.yaml index 9b5a1c7a..65e6e7fc 100644 --- a/swagger.yaml +++ b/swagger.yaml @@ -656,6 +656,10 @@ definitions: - failed description: type: string + instance_usable: + type: boolean + update_repeatable: + type: boolean ServiceBindingResource: type: object properties: @@ -769,7 +773,10 @@ definitions: type: string description: type: string - + instance_usable: + type: boolean + update_repeatable: + type: boolean securityDefinitions: basicAuth: type: basic