Generic Extensions (actions)

spec.md

@@ -841,11 +841,47 @@ 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 on a per Service Instance basis, Service Brokers MAY return one or more objects that describe additional API endpoints via an OpenAPI document. See [Extension APIs Object](#extension-apis-object) for more information. |
+
+##### Extension APIs Object
+
+The `extension_apis` 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 Service Instance provisioning request will return a URI to an OpenAPI 3.0+
+document that the Platform can use to determine the new endpoint(s),
+parameter(s), authentication mechanism and server URL. 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.
+
+Extension API endpoints MAY be executed on a remote server, however the OpenAPI
+document MUST include a Server Object with an accurate `url` parameter and a
+`description` field labeled, "Service Broker Extensions Server". If no Server
+Object `description` field contains, "Service Broker Extensions Server", the 
+Platform MUST assume the extension API endpoints are to be invoked using the
+Service Broker host and port. 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. |
+| 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 `extensions_api` object within the `credentials` field. If credentials are present in an `extensions_api` object, the Platform will need to verify the authentication method from 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",
+      "credentials":[{
+        "tokenURL": "https://example.com/api/oauth/token"
+      }],
+      "adheres_to": "http://example-specification.example.com"
+  }]
 }
 ```