From c1f610a62c3d7f6ecd42aea9d8cc6d50236143f3 Mon Sep 17 00:00:00 2001 From: Matt McNeeney Date: Tue, 21 Mar 2017 17:51:12 +0000 Subject: [PATCH] Add last_operation endpoint for async bindings --- spec.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 68 insertions(+), 16 deletions(-) diff --git a/spec.md b/spec.md index 78af0ad9..ec2f3fe3 100644 --- a/spec.md +++ b/spec.md @@ -11,8 +11,9 @@ - [Synchronous and Asynchronous Operations](#synchronous-asynchronous) - [Synchronous Operations](#synchronous-operations) - [Asynchronous Operations](#asynchronous-operations) - - [Polling Last Operation](#polling) - - [Polling Interval and Duration](#polling-interval-and-duration) + - [Polling Last Service Instance Operation](#polling) + - [Polling Last Service Binding Operation](#polling-binding) + - [Polling Interval and Duration](#polling-interval-and-duration) - [Provisioning](#provisioning) - [Updating a Service Instance](#updating_service_instance) - [Binding](#binding) @@ -279,9 +280,9 @@ An asynchronous response triggers the platform marketplace to poll the endpoint The marketplace must ensure that service brokers do not receive requests for an instance while an asynchronous operation is in progress. For example, if a broker is in the process of provisioning an instance asynchronously, the marketplace must not allow any update, bind, unbind, or deprovision requests to be made through the platform. A user who attempts to perform one of these actions while an operation is already in progress must receive an HTTP 400 response with the error message: `Another operation for this service instance is in progress`.
-## Polling Last Operation +## Polling Last Service Instance Operation -When a broker returns status code `202 ACCEPTED` for [provision](#provisioning), [update](#updating_service_instance), [bind](#binding), [unbind](#unbinding) or [deprovision](#deprovisioning), the platform will begin polling the `/v2/service_instances/:guid/last_operation` endpoint to obtain the state of the last requested operation. The broker response must contain the field `state` and an optional field `description`. +When a broker returns status code `202 ACCEPTED` for [provision](#provisioning), [update](#updating_service_instance) or [deprovision](#deprovisioning), the platform will begin polling the `/v2/service_instances/:instance_id/last_operation` endpoint to obtain the state of the last requested operation. The broker response must contain the field `state` and an optional field `description`. Valid values for `state` are `in progress`, `succeeded`, and `failed`. The platform will poll the `last_operation` endpoint as long as the broker returns `"state": "in progress"`. Returning `"state": "succeeded"` or `"state": "failed"` will cause the platform to cease polling. The value provided for `description` will be passed through to the platform API client and can be used to provide additional detail for users about the progress of the operation. @@ -298,7 +299,7 @@ The request provides these query string parameters as useful hints for brokers. |---|---|---| | service_id | string | ID of the service from the catalog. | | plan_id | string | ID of the plan from the catalog. | -| operation | string | A broker-provided identifier for the operation. When a value for operation is included with asynchronous responses for [Provision](#provisioning), [Update](#updating_service_instance), [Binding](#binding), [Unbinding](#unbinding) and [Deprovision](#deprovisioning) requests, the broker client should provide the same value using this query parameter as a URL-encoded string. | +| operation | string | A broker-provided identifier for the operation. When a value for operation is included with asynchronous responses for [Provision](#provisioning), [Update](#updating_service_instance) and [Deprovision](#deprovisioning) requests, the broker client should provide the same value using this query parameter as a URL-encoded string. |

Note: Although the request query parameters service_id and plan_id are not required, the platform should include them on all last_operation requests it makes to service brokers.

@@ -322,6 +323,56 @@ All response bodies must be a valid JSON Object (`{}`). This is for future compa For success responses, the following fields are valid. +| 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" should cause the platform to cease polling. | +| description | string | Optional field. A user-facing message displayed to the platform API client. Can be used to tell the user details about the status polling-bindingof the operation. | + +\* Fields with an asterisk are required. + +
+## Polling Last Service Binding Operation + +When a broker returns status code `202 ACCEPTED` for [bind](#binding) or [unbind](#unbinding), the platform will begin polling the `/v2/service_instances/:instance_id/service_bindings/:binding_id/last_operation` endpoint to obtain the state of the last requested operation. The broker response must contain the field `state` and an optional field `description`. + +Valid values for `state` are `in progress`, `succeeded`, and `failed`. The platform will poll the `last_operation` endpoint as long as the broker returns `"state": "in progress"`. Returning `"state": "succeeded"` or `"state": "failed"` will cause the platform to cease polling. The value provided for `description` will be passed through to the platform API client and can be used to provide additional detail for users about the progress of the operation. + +### Request ### + +##### Route ##### +`GET /v2/service_instances/:instance_id/service_bindings/:binding_id/last_operation` + +##### Parameters ##### + +The request provides these query string parameters as useful hints for brokers. + +| Query-String Field | Type | Description | +|---|---|---| +| service_id | string | ID of the service from the catalog. | +| plan_id | string | ID of the plan from the catalog. | +| operation | string | A broker-provided identifier for the operation. When a value for operation is included with asynchronous responses for [Binding](#binding) and [Unbinding](#unbinding) requests, the broker client should provide the same value using this query parameter as a URL-encoded string. | + +

Note: Although the request query parameters service_id and plan_id are not required, the platform should include them on all last_operation requests it makes to service brokers.

+ +##### cURL ##### +
+$ curl http://username:password@broker-url/v2/service_instances/:instance_id/service_bindings/:binding_id/last_operation
+
+ +### Response ### + +| Status Code | Description | +|---|---| +| 200 OK | The expected response body is below. | + +Responses with any other status code should be interpreted as an error or invalid response. The platform should continue polling until the broker returns a valid response or the [maximum polling duration](#polling-interval-and-duration) is reached. Brokers may use the `description` field to expose user-facing error messages about the operation state; for more info see [Broker Errors](#broker-errors). + +##### Body ##### + +All response bodies must be a valid JSON Object (`{}`). This is for future compatibility; it will be easier to add fields in the future if JSON is expected rather than to support the cases when a JSON body may or may not be returned. + +For success responses, the following fields are valid. + | 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" should cause the platform to cease polling. | @@ -332,15 +383,16 @@ For success responses, the following fields are valid. 
 {
   "state": "in progress",
-  "description": "Creating service (10% complete)."
+  "description": "Binding service (10% complete)."
 }
-### Polling Interval and Duration +## Polling Interval and Duration The frequency and maximum duration of polling may vary by platform client. If a platform has a max polling duration and this limit is reached, the platform will cease polling and the operation state will be considered `failed`. +
## Provisioning @@ -398,7 +450,7 @@ $ curl http://username:password@broker-url/v2/service_instances/:instance_id -d |---|---| | 201 Created | Service instance has been provisioned. The expected response body is below. | | 200 OK | May be returned if the service instance already exists and the requested parameters are identical to the existing service instance. The expected response body is below. | -| 202 Accepted | Service instance provisioning is in progress. This triggers the platform marketplace to poll the [Service Instance Last Operation Endpoint](#polling) for operation status. | +| 202 Accepted | Service instance provisioning is in progress. This triggers the platform marketplace to poll the [Last Service Instance Operation Endpoint](#polling) for operation status. | | 409 Conflict | Should be returned if a service instance with the same id already exists but with different attributes. The expected response body is {}. | | 422 Unprocessable Entity | Should be returned if the broker only supports asynchronous provisioning for the requested plan and the request did not include ?accepts_incomplete=true. The expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }, as described below. | @@ -414,7 +466,7 @@ For success responses, a broker may return the following fields. For error respo | Response field | Type | Description | |---|---|---| | dashboard_url | string | The URL of a web-based management user interface for the service instance; we refer to this as a service dashboard. The URL should contain enough information for the dashboard to identify the resource being accessed (9189kdfsk0vfnku in the example below). | -| operation | string | For asynchronous responses, service brokers may return an identifier representing the operation. The value of this field should be provided by the broker client with requests to the [Last Operation](#polling) endpoint in a URL encoded query parameter. | +| operation | string | For asynchronous responses, service brokers may return an identifier representing the operation. The value of this field should be provided by the broker client with requests to the [Last Service Instance Operation](#polling) endpoint in a URL encoded query parameter. | \* Fields with an asterisk are required. @@ -497,7 +549,7 @@ $ curl http://username:password@broker-url/v2/service_instances/:instance_id -d | Status Code | Description | |---|---| | 200 OK | The requests changes have been applied. The expected response body is {}. | -| 202 Accepted | Service instance update is in progress. This triggers the platform marketplace to poll the [Service Instance Last Operation Endpoint](#polling) for operation status. | +| 202 Accepted | Service instance update is in progress. This triggers the platform marketplace to poll the [Last Service Instance Operation Endpoint](#polling) for operation status. | | 422 Unprocessable entity | May be returned if the requested change is not supported or if the request cannot currently be fulfilled due to the state of the instance (e.g. instance utilization is over the quota of the requested plan). Broker should include a user-facing message in the body; for details see [Broker Errors](#broker-errors). Additionally, a 422 can also be returned if the broker only supports asynchronous update for the requested plan and the request did not include ?accepts_incomplete=true; in this case the expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." } | Responses with any other status code will be interpreted as a failure. Brokers can include a user-facing message in the `description` field; for details see [Broker Errors](#broker-errors). @@ -510,7 +562,7 @@ For success responses, a broker may return the following field. Others will be i | Response field | Type | Description | |---|---|---| -| operation | string | For asynchronous responses, service brokers may return an identifier representing the operation. The value of this field should be provided by the broker client with requests to the [Last Operation](#polling) endpoint in a URL encoded query parameter. | +| operation | string | For asynchronous responses, service brokers may return an identifier representing the operation. The value of this field should be provided by the broker client with requests to the [Last Service Instance Operation](#polling) endpoint in a URL encoded query parameter. | \* Fields with an asterisk are required. @@ -612,7 +664,7 @@ $ curl http://username:password@broker-url/v2/service_instances/:instance_id/ser |---|---| | 201 Created | Binding has been created. The expected response body is below. | | 200 OK | May be returned if the binding already exists and the requested parameters are identical to the existing binding. The expected response body is below. | -| 202 Accepted | Service instance provisioning is in progress. This triggers the platform marketplace to poll the [Service Instance Last Operation Endpoint](#polling) for operation status. | +| 202 Accepted | Service instance provisioning is in progress. This triggers the platform marketplace to poll the [Last Service Binding Operation Endpoint](#polling-binding) for operation status. | | 409 Conflict | Should be returned if the requested binding already exists. The expected response body is {}, though the description field can be used to return a user-facing error message, as described in [Broker Errors](#broker-errors). | | 422 Unprocessable Entity | Should be returned if the broker requires that app_guid be included in the request body. The expected response body is: { "error": "RequiresApp", "description": "This service supports generation of credentials through binding an application only." } Additionally, a 422 can also be returned if the broker only supports asynchronous binding for the requested plan and the request did not include ?accepts_incomplete=true; in this case the expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." } | @@ -630,7 +682,7 @@ For success responses, the following fields are supported. Others will be ignore | syslog\_drain_url | string | A URL to which logs may be streamed. "requires":["syslog\_drain"] must be declared in the [Catalog](#catalog-mgmt) endpoint or the platform should consider the response invalid. | | route\_service_url | string | A URL to which the platform may proxy requests for the address sent with bind\_resource.route in the request body. "requires":["route\_forwarding"] must be declared in the [Catalog](#catalog-mgmt) endpoint or the platform should consider the response invalid. | | volume\_mounts | array-of-objects | An array of configuration for mounting volumes. "requires":["volume_mount"] must be declared in the [Catalog](#catalog-mgmt) endpoint or the platform should consider the response invalid. | -| operation | string | For asynchronous responses, service brokers may return an identifier representing the operation. The value of this field should be provided by the broker client with requests to the [Last Operation](#polling) endpoint in a URL encoded query parameter. | +| operation | string | For asynchronous responses, service brokers may return an identifier representing the operation. The value of this field should be provided by the broker client with requests to the [Last Service Binding Operation](#polling-binding) endpoint in a URL encoded query parameter. | 
     {
@@ -682,7 +734,7 @@ $ curl 'http://username:password@broker-url/v2/service_instances/:instance_id/
 | Status Code  | Description  |
 |---|---|
 | 200 OK  | Binding was deleted. The expected response body is {}.  |
-| 202 Accepted  | Service instance provisioning is in progress. This triggers the platform marketplace to poll the [Service Instance Last Operation Endpoint](#polling) for operation status. |
+| 202 Accepted  | Service instance provisioning is in progress. This triggers the platform marketplace to poll the [Last Service Binding Operation Endpoint](#polling-binding) for operation status. |
 | 410 Gone  | Should be returned if the binding does not exist. The expected response body is {}.  |
 | 422 Unprocessable Entity  | Should be returned if the broker only supports asynchronous unbinding for the requested plan and the request did not include ?accepts_incomplete=true; in this case the expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." } |
 
@@ -698,7 +750,7 @@ For success responses, the following fields are supported. Others will be ignore
 
 |  Response field | Type | Description |
 |---|---|---|
-| operation  | string  | For asynchronous responses, service brokers may return an identifier representing the operation. The value of this field should be provided by the broker client with requests to the [Last Operation](#polling) endpoint in a URL encoded query parameter. |
+| operation  | string  | For asynchronous responses, service brokers may return an identifier representing the operation. The value of this field should be provided by the broker client with requests to the [Last Service Binding Operation](#polling-binding) endpoint in a URL encoded query parameter. |
 
 
 
@@ -746,7 +798,7 @@ $ curl 'http://username:password@broker-url/v2/service_instances/:instance_id?se
 | Status Code | Description |
 |---|---|
 | 200 OK | Service instance was deleted. The expected response body is {}. |
-| 202 Accepted | Service instance deletion is in progress. This triggers the marketplace to poll the [Service Instance Last Operation Endpoint](#polling) for operation status.  |
+| 202 Accepted | Service instance deletion is in progress. This triggers the marketplace to poll the [Last Service Instance Operation Endpoint](#polling) for operation status.  |
 | 410 Gone | Should be returned if the service instance does not exist. The expected response body is {}.  |
 | 422 Unprocessable Entity | Should be returned if the broker only supports asynchronous deprovisioning for the requested plan and the request did not include ?accepts_incomplete=true. The expected response body is: { "error": "AsyncRequired", "description": "This service plan requires client support for asynchronous service operations." }, as described below.  |