From 60e80f8a5bbea66c9ad78c583c70acfcec63c192 Mon Sep 17 00:00:00 2001 From: rohitkshetty Date: Sat, 13 May 2017 23:09:44 -0400 Subject: [PATCH 1/4] Action Execution --- spec.md | 240 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 240 insertions(+) diff --git a/spec.md b/spec.md index 448b4ffd..45497a86 100644 --- a/spec.md +++ b/spec.md @@ -746,6 +746,246 @@ For success responses, the following fields are supported. Others will be ignore } +# Service Instance Actions +These are any actions that a broker allows w.r.t the service instances that it manages. The actions here could be anything that the service broker wants to provide and the platform shouldnt have to care what these are. The actions are discoverable by the platform and since the platform has absolutely no clue what these actions are there would be user interaction involved where the actions are presented to the user by the platform and the user performs the action with any input thats required. + +## Action Discovery +By Implementing this endpoint the broker allows the platform to query the actions allowed on a service instance at any point in time. The list of actions returned by the endpoint is dynamic and could depend on the service instance and its internal state. + +##### Route ##### +`GET /v2/service_instances/:instance_id/actions` + +The `:instance_id` of a service instance that has been provisioned previously. + +#### cURL #### +
+ $ curl -H "X-Broker-API-Version: 2.11" http://username:password@broker-url/v2/service_instances/:instance_id/actions
+
+ +### Response ### + +| Status Code | Description | +|---|---| +| 200 OK | The expected response body is below. | + +##### Action ##### + +| Response field | Type | Description | +|---|---|---| +| id* | string | A unique identifier for the action. Using a GUID is RECOMMENDED. | +| name* | string | The CLI-friendly name of the action. MUST be unique within the service. All lowercase, no spaces. | +| displayName* | string | The display friendly name of the action that would be used for display in the UI and CLI | +| description* | string | A short description of the action. | +| parameters | array-of-objects | An array of parameters required by the action. | + + +##### Parameter ##### + +| Response field | Type | Description | +|---|---|---| +| name* | string | The CLI-friendly name of the parameter. MUST be unique within the action. All lowercase, no spaces. | +| displayName* | string | The display friendly name of the parameter that would be used for display in the UI and CLI | +| description* | string | A short description of the parameter. | +| value | string | An indication to the platform to provide a default value for the parameter. | +| options | array-of-strings | A array of values that can be provided as a list of choices to the user. | + +\* Fields with an asterisk are REQUIRED. + +
+{
+  "actions": [{
+    "name": "fake-backup-action",
+    "displayName": "Run periodic backup",
+    "id": "acb56222-XXXX-XXXX-XXXX-feb140a59a66",
+    "description": "Runs and enables periodic service instance backup",
+    "parameters": [{
+      "name": "fake-backup-int-param",
+      "displayName": "Backup Interval (days)",
+      "id": "d3031751-XXXX-XXXX-XXXX-a42377d33222",
+      "description": "Provide the interval at which the service instance data should be backed up",
+      "value": "1",
+      "options": ["1", "2", "3"]
+    }, {
+      "name": "fake-backup-retention-param",
+      "displayName": "Retention Period (days)",
+      "description": "Provide the retention period for the backed up data",
+      "value": "90"
+    }]
+  }, {
+    "name": "fake-restart-action",
+    "displayName": "Restart Service",
+    "description": "Restart the service"
+  }]
+}
+
+ +## Get an Action +Retrieve a single action + +##### Route ##### +`GET /v2/service_instances/:instance_id/actions/:action_id` + +The `:action_id` of a action. +The `:instance_id` of a service instance that has been provisioned previously. + +#### cURL #### +
+ $ curl -H "X-Broker-API-Version: 2.11" http://username:password@broker-url/v2/service_instances/:instance_id/actions/:action_id
+
+ +### Response ### + +| Status Code | Description | +|---|---| +| 200 OK | The expected response body is below. | + +##### Action ##### + +| Response field | Type | Description | +|---|---|---| +| id* | string | A unique identifier for the action. Using a GUID is RECOMMENDED. | +| name* | string | The CLI-friendly name of the action. MUST be unique within the service. All lowercase, no spaces. | +| displayName* | string | The display friendly name of the action that would be used for display in the UI and CLI | +| description* | string | A short description of the action. | +| parameters | array-of-objects | An array of parameters required by the action. | + + +##### Parameter ##### + +| Response field | Type | Description | +|---|---|---| +| name* | string | The CLI-friendly name of the parameter. MUST be unique within the action. All lowercase, no spaces. | +| displayName* | string | The display friendly name of the parameter that would be used for display in the UI and CLI | +| description* | string | A short description of the parameter. | +| value | string | An indication to the platform to provide a default value for the parameter. | +| options | array-of-strings | A array of values that can be provided as a list of choices to the user. | + +\* Fields with an asterisk are REQUIRED. + +
+{
+    "name": "fake-backup-action",
+    "displayName": "Run periodic backup",
+    "id": "acb56222-XXXX-XXXX-XXXX-feb140a59a66",
+    "description": "Runs and enables periodic service instance backup",
+    "parameters": [{
+      "name": "fake-backup-int-param",
+      "displayName": "Backup Interval (days)",
+      "description": "Provide the interval at which the service instance data should be backed up",
+      "value": "1",
+      "options": ["1", "2", "3"]
+    }, {
+      "name": "fake-backup-retention-param",
+      "displayName": "Retention Period (days)",
+      "description": "Provide the retention period for the backed up data",
+      "value": "90"
+    }]
+}
+
+ +## Action Execution +Platform invokes this endpoint to submit execution requests for the actions for a service instance. The requests are assynchronous by nature and the status can be queried by the platform. + +##### Route ##### +`PUT /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id` + +The `:action_id` of a action being executed. +The `:instance_id` of a service instance that has been provisioned previously. +The `:execution_id` of an execution is provided by the platform. This ID will be used for future requests (get status and cancel), so the broker will use it to correlate the action it performs. + +##### Body ##### +| Request field | Type | Description | +|---|---|---| +| action_id* | string | The ID of the action (from the action discovery). MUST be globally unique. | +| parameters | array-of-objects | An array of parameters required by the action. | + +\* Fields with an asterisk are REQUIRED. + +
+{
+  "action_id": "action-guid-here",
+  "parameters": [{
+      "name": "fake-backup-int-param",
+      "value": "1"
+    }, {
+      "name": "fake-backup-retention-param",
+      "value": "90"
+    }]
+}
+
+ +##### cURL ##### +
+$ curl http://username:password@broker-url//v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id -d '{
+  "action_id": "action-guid-here",
+  "parameters": [{
+      "name": "fake-backup-int-param",
+      "value": "1"
+    }, {
+      "name": "fake-backup-retention-param",
+      "value": "90"
+    }]
+}' -X PUT -H "X-Broker-API-Version: 2.11" -H "Content-Type: application/json"
+
+ +## Get Action Execution status +Retrieve the status of an action execution. + +##### Route ##### +`GET /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id` + +The `:action_id` of a action being executed. +The `:instance_id` of a service instance that has been provisioned previously. +The `:execution_id` of an execution is provided by the platform. + +#### cURL #### +
+ $ curl -H "X-Broker-API-Version: 2.11" http://username:password@broker-url/v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id
+
+ +### Response ### + +| Status Code | Description | +|---|---| +| 200 OK | The expected response body is below. | + +##### Body ##### + +| Response field | Type | Description | +|---|---|---| +| state* | string | Valid values are in progress, succeeded, cancelled, and failed. + +\* Fields with an asterisk are REQUIRED. + +
+{
+  "state": "in progress",
+  "description": "Restarting (10% complete)."
+}
+
+ +## Cancel Action Execution +Cancel the execution of an action. + +##### Route ##### +`DELETE /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id` + +The `:action_id` of a action being executed. +The `:instance_id` of a service instance that has been provisioned previously. +The `:execution_id` of an execution is provided by the platform. + +#### cURL #### +
+ $ curl -X DELETE -H "X-Broker-API-Version: 2.11" http://username:password@broker-url/v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id
+
+ +### Response ### + +| Status Code | Description | +|---|---| +| 202 Accepted | Action execution cancellation is in progress. +| 409 Conflict | If the action execution cannot be cancelled. + ## Broker Errors ### Response ### From 3d0fc5cf34ca78566b0eb208a16b48cd92c475ea Mon Sep 17 00:00:00 2001 From: rohitkshetty Date: Mon, 15 May 2017 20:40:48 -0400 Subject: [PATCH 2/4] updating status strings --- spec.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 45497a86..75748d16 100644 --- a/spec.md +++ b/spec.md @@ -954,13 +954,16 @@ The `:execution_id` of an execution is provided by the platform. | Response field | Type | Description | |---|---|---| | state* | string | Valid values are in progress, succeeded, cancelled, and failed. +| description* | string | Description or message about the status of the operation. +| detailedMessage | string | Detailed stdout/stderr from the action being performed. \* Fields with an asterisk are REQUIRED. 
 {
   "state": "in progress",
-  "description": "Restarting (10% complete)."
+  "description": "Restarting (10% complete).",
+  "detailedMessage": "space for detailed stdout/stderr"
 }
From 5442a650c0348d428a34bb33cf2e226951932b26 Mon Sep 17 00:00:00 2001 From: rohitkshetty Date: Tue, 16 May 2017 19:51:42 -0400 Subject: [PATCH 3/4] Update spec.md --- spec.md | 28 ++++++++++++++++++++++------ 1 file changed, 22 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 75748d16..ceee5c91 100644 --- a/spec.md +++ b/spec.md @@ -887,7 +887,7 @@ The `:instance_id` of a service instance that has been provisioned previously. Platform invokes this endpoint to submit execution requests for the actions for a service instance. The requests are assynchronous by nature and the status can be queried by the platform. ##### Route ##### -`PUT /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id` +`POST /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id` The `:action_id` of a action being executed. The `:instance_id` of a service instance that has been provisioned previously. @@ -971,22 +971,38 @@ The `:execution_id` of an execution is provided by the platform. Cancel the execution of an action. ##### Route ##### -`DELETE /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id` +`PUT /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id` The `:action_id` of a action being executed. The `:instance_id` of a service instance that has been provisioned previously. -The `:execution_id` of an execution is provided by the platform. +The `:execution_id` of an execution is provided by the platform. This ID will be used for future requests (get status and cancel), so the broker will use it to correlate the action it performs. -#### cURL #### +##### Body ##### +| Request field | Type | Description | +|---|---|---| +| state* | string | The ID of the action (from the action discovery). MUST be globally unique. | +| parameters | array-of-objects | An array of parameters required by the action. | + +\* Fields with an asterisk are REQUIRED. + +
+{
+  "state": "cancelled"
+}
+
+ +##### cURL ##### 
- $ curl -X DELETE -H "X-Broker-API-Version: 2.11" http://username:password@broker-url/v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id
+$ curl http://username:password@broker-url//v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id -d '{
+  "state": "cancelled"
+}' -X PUT -H "X-Broker-API-Version: 2.11" -H "Content-Type: application/json"
### Response ### | Status Code | Description | |---|---| -| 202 Accepted | Action execution cancellation is in progress. +| 202 Accepted | Action execution cancellation is in progress and a get execution status would return a "cancelled" status. | 409 Conflict | If the action execution cannot be cancelled. ## Broker Errors From a597cf8433c8ef3f8d2a2cfc4e036655b59f6271 Mon Sep 17 00:00:00 2001 From: rohitkshetty Date: Tue, 16 May 2017 19:52:43 -0400 Subject: [PATCH 4/4] Update --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index ceee5c91..ed08b45d 100644 --- a/spec.md +++ b/spec.md @@ -971,7 +971,7 @@ The `:execution_id` of an execution is provided by the platform. Cancel the execution of an action. ##### Route ##### -`PUT /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id` +`PUT /v2/service_instances/:instance_id/actions/:action_id/executions/:execution_id` The `:action_id` of a action being executed. The `:instance_id` of a service instance that has been provisioned previously.