Generic Extensions (actions)

spec.md

@@ -841,11 +841,46 @@ 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 indended to be invokved 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 server location, endpoints, parameters 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. MUST be a valid URI. 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. |
+| 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, (e.g. an OAuth Flow Object), and the appropriate credential(s), (e.g. bearer token), as part of the `extension_api` object within the `credentials` field. 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. |
+| 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.
 
 ```
 {
   "dashboard_url": "http://example-dashboard.example.com/9189kdfsk0vfnku",
-  "operation": "task_10"
+  "operation": "task_10",
+  "extension_apis":[{
+      "discovery_url": "http://example-openapi-doc.example.com/extensions",
+      "server_url": "http://myremoteserver.example.com",
+      "credentials":[{
+        "tokenURL": "https://example.com/api/oauth/token"
+      }],
+      "alt_instance_id": "serviceInstance",
+      "adheres_to": "http://example-specification.example.com"
+  }]
 }
 ```