Skip to content

Remove ambiguity on provisioning status code #717

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
rsampaio merged 8 commits into from
Nov 24, 2020
Merged

Remove ambiguity on provisioning status code #717

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
99b8505
Remove ambiguity on provisioning status code
rsampaio Jun 9, 2020
7475bc2
add guidance for platforms that rely on eventual consistency
rsampaio Jun 9, 2020
651ac15
Revert "Remove ambiguity on provisioning status code"
rsampaio Jun 23, 2020
670a57e
fix typo
rsampaio Jul 7, 2020
cc93eef
deprecated the use of 200 response
rsampaio Jul 7, 2020
8addfd4
clarify even more the use of 200 status and use consistent language f…
rsampaio Jul 23, 2020
64a376d
clarify status code for async and sync
rsampaio Oct 13, 2020
0dae18c
fix table formatting
rsampaio Oct 27, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -675,7 +675,13 @@ Offering, even by Service Plan.

To execute a request synchronously, the Service Broker need only return the
usual status codes: `201 Created` for provision and bind, and `200 OK` for
update, unbind, and deprovision.
update, unbind, and deprovision. `200 OK` MAY be returned synchronously by
Service Brokers that accept provisioning requests with unchanged parameters
and synchronous operations.

Platforms that rely on eventual consistency are RECOMMENDED to use `409 Conflict`
as a no-op response and SHOULD use the `last_operation` endpoint to verify the status of
the provisioning request instead in asynchronous mode.

Service Brokers that support synchronous responses for provision, update, and
delete can ignore the `accepts_incomplete=true` query parameter if it is
Expand Down Expand Up @@ -985,7 +991,7 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc

| Status Code | Description |
| --- | --- |
| 200 OK | SHOULD be returned if the Service Instance already exists, is fully provisioned, and the requested parameters are identical to the existing Service Instance. The expected response body is below. |
| 200 OK | SHOULD be returned if the Service Instance already exists, is fully provisioned, and the requested parameters are identical to the existing Service Instance. The expected response body is below. *This response is only valid in synchronous operations*. |
| 201 Created | MUST be returned if the Service Instance was provisioned as a result of this request. The expected response body is below. |
| 202 Accepted | MUST be returned if the Service Instance provisioning is in progress. The `operation` string MUST match that returned for the original request. This triggers the Platform to poll the [Last Operation for Service Instances](#polling-last-operation-for-service-instances) endpoint for operation status. Note that a re-sent `PUT` request MUST return a `202 Accepted`, not a `200 OK`, if the Service Instance is not yet fully provisioned. |
| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. MAY be returned if the request contains invalid data, in which case the error response MAY include a helpful error message in the `description` field (see [Service Broker Errors](#service-broker-errors)). |
Expand Down Expand Up @@ -1489,7 +1495,7 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc

| Status Code | Description |
| --- | --- |
| 200 OK | SHOULD be returned if the Service Binding already exists and the requested parameters are identical to the existing Service Binding. The expected response body is below. |
| 200 OK | SHOULD be returned if the Service Binding already exists and the requested parameters are identical to the existing Service Binding. The expected response body is below. *This response is only valid in synchronous operations*. |
| 201 Created | MUST be returned if the Service Binding was created as a result of this request. The expected response body is below. |
| 202 Accepted | MUST be returned if the binding is in progress. The `operation` string MUST match that returned for the original request. This triggers the Platform to poll the [Polling Last Operation for Service Bindings](#polling-last-operation-for-service-bindings) endpoint for operation status. Information regarding the Service Binding (i.e. credentials) MUST NOT be returned in this response. Note that a re-sent `PUT` request MUST return a `202 Accepted`, not a `200 OK`, if the Service Binding is not yet fully created. |
| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. MAY be returned if the request contains invalid data, in which case the error response MAY include a helpful error message in the `description` field (see [Service Broker Errors](#service-broker-errors)). |
Expand Down Expand Up @@ -1522,8 +1528,8 @@ For `200 OK` and `201 Created` response codes, the following fields are defined:

| Response Field | Type | Description |
| --- | --- | --- |
| expires_at | string | The date and time when the Service Binding becomes invalid and SHOULD NOT or CANNOT be used anymore. If present, the string MUST follow ISO 8601 and this pattern: `yyyy-mm-ddThh:mm:ss.sZ` |
| renew_before | string | The date and time before the Service Binding SHOULD be renewed. Applications or Platforms MAY use this field to initiate a [Service Binding rotation](#binding-rotation) or create a new Service Binding on time. It is RECOMMENDED to trigger the creation of a new Service Binding shortly before this timestamp. If the `expires_at` field is also present, the `renew_before` timestamp MUST be before or equal to the `expires_at` timestamp. Service Brokers SHOULD leave enough time between both timestamps to create a new Service Binding including a buffer to enable continuity. If present, the string MUST follow ISO 8601 and this pattern: `yyyy-mm-ddThh:mm:ss.sZ` |
| expires_at | string | The date and time when the Service Binding becomes invalid and SHOULD NOT or CANNOT be used anymore. If present, the string MUST follow ISO 8601 and this pattern: `yyyy-mm-ddThh:mm:ss.sZ`. |
| renew_before | string | The date and time before the Service Binding SHOULD be renewed. Applications or Platforms MAY use this field to initiate a [Service Binding rotation](#binding-rotation) or create a new Service Binding on time. It is RECOMMENDED to trigger the creation of a new Service Binding shortly before this timestamp. If the `expires_at` field is also present, the `renew_before` timestamp MUST be before or equal to the `expires_at` timestamp. Service Brokers SHOULD leave enough time between both timestamps to create a new Service Binding including a buffer to enable continuity. If present, the string MUST follow ISO 8601 and this pattern: `yyyy-mm-ddThh:mm:ss.sZ`. |

##### Volume Mount Object

Expand Down Expand Up @@ -1914,7 +1920,7 @@ by the Platform:

| Request | Service Broker Response Status Code | Platform Interpretation Of Response | Orphan Mitigation SHOULD be performed for Service Instances | Orphan Mitigation SHOULD be performed for Service Bindings |
| --- | --- | --- | --- | --- |
| _All_ | 200 | Success | No | No |
| _All_ | 200 | Success (only returned in synchronous mode) | No | No |
| _All_ | 200 with malformed response | Failure | No | No |
| [Polling Last Operation for Service Instances](#polling-last-operation-for-service-instances) for [Provisioning](#provisioning)/[Deprovisioning](#deprovisioning) | 200 with `"state": "failed"` | Failure | Yes | No |
| [Polling Last Operation for Service Bindings](#polling-last-operation-for-service-bindings) for [Binding](#binding)/[Unbinding](#unbinding) | 200 with `"state": "failed"` | Failure | No | Yes |
Expand Down