diff --git a/spec.md b/spec.md index 9bfb077f..79f37f30 100644 --- a/spec.md +++ b/spec.md @@ -29,6 +29,7 @@ - [Fetching a Service Binding](#fetching-a-service-binding) - [Unbinding](#unbinding) - [Deprovisioning](#deprovisioning) + - [Corrupt Service Instances](#corrupt-service-instances) - [Orphans](#orphans) ## API Overview @@ -768,7 +769,10 @@ 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. | +| status_code | number | The HTTP status code that would have been returned if the operation would have been executed synchronously. If the state is `failed` this field SHOULD be present and the value MUST be an integer in the range of 400 to 599. This field MUST NOT be present for any other state. | +| error | string | An error code as described in the [Service Broker Errors](#service-broker-errors) section. If present, MUST be a non-empty string. If the state is `failed` and there is an error code this field SHOULD be present. This field MUST NOT be present for any other state. | \* Fields with an asterisk are REQUIRED. @@ -1155,9 +1159,13 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc | 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | | 422 Unprocessable entity | MUST be returned if the requested change is not supported or if the request cannot currently be fulfilled due to the state of the Service Instance (e.g. Service Instance utilization is over the quota of the requested plan). Additionally, a `422 Unprocessable Entity` MUST be returned if the Service Broker only supports asynchronous update for the requested plan and the request did not include `?accepts_incomplete=true`; in this case the response body MUST contain a error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. | -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. +apply any of the requested changes to the Service Instance and the +Service Instance MUST be in an unmodified and usable state. + +Responses with any other status code MUST be interpreted as a failure. +The Service Instance MUST be considered corrupt and the Platform SHOULD NOT +allow the creation of new bindings. #### Body @@ -1599,8 +1607,13 @@ $ curl 'http://username:password@service-broker-url/v2/service_instances/:instan | 410 Gone | MUST be returned if the Service Instance does not exist. | | 422 Unprocessable Entity | MUST be returned if the Service Broker only supports asynchronous deprovisioning for the requested plan and the request did not include `?accepts_incomplete=true`. The response body MUST contain error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. | +When the response includes a 4xx status code other than 410 Gone, the +Service Instance MUST be in an unmodified and usable state. + Responses with any other status code MUST be interpreted as a failure and the -Platform MUST remember the Service Instance. +Platform MUST remember the Service Instance. The Service Instance MUST be +considered corrupt and the Platform SHOULD NOT allow the creation of +new bindings. #### Body @@ -1616,6 +1629,18 @@ For success responses, the following fields are defined: } ``` +## Corrupt Service Instances + +When an update or delete operation fails, the Service Instance MAY be corrupt. +A corrupt instance MAY be misconfigured, in an invalid state, not reachable, or +not working at all. +Platforms SHOULD NOT try to create bindings for this instance anymore. +Whether or not a corrupt instance can be repaired by, for example, updating it +again, is undefined. +Deprovisioning a corrupt instance SHOULD still be possible. A Platform MUST +remember the Service Instance until it is successfully deprovisioned or it has +been cleaned up as an orphan. + ## Orphans The Platform is the source of truth for Service Instances and Service Bindings.