Generic Extensions (actions)

spec.md

@@ -841,13 +841,113 @@ For success responses, the following fields are defined:
 | --- | --- | --- |
 | 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 MUST contain enough information for the dashboard to identify the resource being accessed (`9189kdfsk0vfnku` in the example below). Note: a Service Broker that wishes to return `dashboard_url` for a Service Instance MUST return it with the initial response to the provision request, even if the service is provisioned asynchronously. If present, MUST be a non-empty string. |
 | operation | string | For asynchronous responses, Service Brokers MAY return an identifier representing the operation. The value of this field MUST be provided by the Platform with requests to the [Last Operation](#polling-last-operation) endpoint in a percent-encoded query parameter. If present, MUST be a non-empty string. |
+| extension_apis | array-of-objects | For extensions to the Service Broker API, Service Brokers MAY return one or more `extension_api` objects that describe additional API endpoints via an OpenAPI document. See [Extension API Object](#extension-api-object) for more information. |
+
+##### Extension API Object
+
+The `extension_api` object MAY be used to describe any additional endpoint
+to the Open Service Broker API. An example of this could be lifecycle
+management of a Service Instance, (e.g. "Day Two Operations"), like Backup,
+Restore, Stop, Start, Restart and Pause.
+
+The `extension_api` MUST include a URI to an OpenAPI 3.0+ document that the
+Platform can use to determine the new endpoint(s), parameter(s) and
+authentication mechanism. The new APIs are extensions to the Open Service Broker
+API. As such they are intended to be invoked by the Platform on behalf of its
+clients.
+
+See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#serverObject) for more information.
+
+| Response Field | Type | Description |
+| --- | --- | --- |
+| discovery_url* | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Open Service Broker API including, endpoints, parameters, authentication mechanism and any other detail the platform needs for invocation. The location of the API extension endpoint(s) can be local to the Service Broker or on a remote server. If located on a remote server acccessing the OpenAPI document MUST NOT require authentication. MUST be a valid URI. If `discovery_url` is a path, the Platform can assume it is to be called relative to the basepath of the Service Broker. The returned OpenAPI document MUST be in json format. See the [OpenAPI Specification](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md) for more information. |
+| server_url | string | A URI pointing to a remote server where API extensions will run. This URI will be used as the basepath for the endpoint(s) described by the `discovery_url` OpenAPI document. If no `server_url` is present, the Platform MUST assume the extension API endpoint(s) are to be invoked using the Service Broker host and port. If present, MUST be a valid URI. If `server_url` is a path, the Platform can assume it is to be called relative to the basepath of the Service Broker. |
+| credentials | object | A Service Broker MAY return authentication details for running any of the extension API calls, especially for those running on remote servers. If not present, the same authentication mechanism used for the normal Open Service Broker APIs MUST work for the new endpoint(s). If the Service Broker wants to use alternate methods of authentication, (e.g. on remote servers) it MUST provide details to that mechanism in the OpenAPI document via one or more [Security Scheme Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securitySchemeObject). Next, each extension endpoint in the OpenAPI document MUST have one or more [Security Requirement Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securityRequirementObject) defined that matches a [Security Scheme Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securitySchemeObject). Lastly, the parameters needed by each [Security Scheme Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#securitySchemeObject), (e.g. username and password for basic authentication), MUST be provided as part of the `extension_api` object within the `credentials` object. If credentials are present in an `extension_api` object, the Platform will need to verify the authentication method from the OpenAPI document. |
+| alt_instance_id | string | Refers to a parameter in the `discovery_url` OpenAPI document that maps directly to the Service Broker API `instance_id` parameter. If the extension API endpoint(s) use a different value to represent a Service Broker instance, then `alt_instance_id` MUST be present. If not present, the Platform can assume `instance_id` means Service Broker Instance in the OpenAPI document. |
+| operation_display_names | object | A Service Broker MAY match operations in the `discovery_url` OpenAPI document with user consumable display names. If present, each key in this object MUST match an [operationID](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject) from the `discovery_url` OpenAPI document, with each value representing a human readable string. Platforms can use this object to show end users operations that are available on their Service Instance prior to calling the `discovery_url` OpenAPI document. |
+| adheres_to | string | A URI refering to a specification detailing the implementation guidelines for the OpenAPI document hosted at the `discovery_url`. While this property is a URI, there is no requirement for there to be an actual server listening at that endpoint. This value is meant to provide a unique identifier representing the set of extensions APIs supported. If present, MUST be a valid URI. |
+
+\* Fields with an asterisk are REQUIRED.
+
+#### Provisioning response
 
 ```
 {
   "dashboard_url": "http://example-dashboard.example.com/9189kdfsk0vfnku",
   "operation": "task_10"
 }
 ```
+#### Provisioning response with extentions
+
+```
+{
+  "dashboard_url": "http://example-dashboard.example.com/9189kdfsk0vfnku",
+  "operation": "task_10",
+  "extension_apis":[{
+      "discovery_url": "http://example-openapi-doc.example.com/extensions",
+      "server_url": "http://myremoteserver.example.com",
+      "credentials": {
+        "basic": {
+          "username": "admin",
+          "password": "changeme"
+        },
+        "api_key": {
+          "api_key": "some_key_value"
+        },
+        "petstore_auth": {
+          "token": "some_token_value"
+        }
+      },
+      "operation_display_names": {
+        "createBackup": "Take Backup",
+        "postRestore": "Restore Instance"
+      },      
+      "alt_instance_id": "serviceInstance",
+      "adheres_to": "http://example-specification.example.com"
+  }]
+}
+```
+
+#### OpenAPI Security Scheme Object example
+
+```
+ "securitySchemes": {
+    "basic": {
+      "type": "http",
+      "scheme": "basic"
+    },   
+    "api_key": {
+      "type": "apiKey",
+      "name": "api_key",
+      "in": "header"
+    },
+    "petstore_auth": {
+      "type": "oauth2",
+      "flows": {
+        "implicit": {
+          "authorizationUrl": "http://example.org/api/oauth/dialog",
+          "scopes": {
+            "write:pets": "modify pets in your account",
+            "read:pets": "read your pets"
+          }
+        }
+      }
+    }
+  }
+```
+#### OpenAPI Path Object example
+
+```
+  "post": {
+    "summary": "Backup Service Instance",
+    "operationId": "createBackup",
+    "responses": {
+      "201": {
+        "description": "backup response.",
+      }
+    }
+  }
+```
 
 ## Updating a Service Instance