From c590bd5b0a126c99be467a03ab6c3d61733fc8e8 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Thu, 25 Jan 2018 17:38:49 -0500 Subject: [PATCH 01/29] actions first draft --- spec.md | 38 +++++++++++++++++++++++++++++++++++++- 1 file changed, 37 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 861183cc..210e7d4b 100644 --- a/spec.md +++ b/spec.md @@ -841,11 +841,29 @@ 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. | +| extention_apis | array-of-objects | For extentions to the Service Broker API on a per Service Instance basis, Service Brokers MAY return one or more objects that desribe additional API endpoints via an OpenAPI document. See [Extention APIs Object](#extention-apis-object) for more information.| + +##### Exention APIs Object + +The `extention_api` object MAY be used to desribe any additional endpoint needed related to a Service Instance. An examples of this might include backup and restore endpoints for a database. If present, MUST return a `discovery_url`. See [Extentions](#extentions) for more information. + +| Response field | Type | Description | +| --- | --- | --- | +| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extention(s) to the Service Instance including server location, endpoints, parameters and any other detail required for invocation. The location of the API extention endpoint(s) can be local to the Service Broker or on a remote server. The Platform MUST execute these API extentions on behalf of the client. MUST be a valid URI. See [OpenAPI](#openapi-document) for more information.| +| credentials | object | A Service Broker MAY return authentication details for running any of the extention API calls, especially for those running on remote servers. If not present, platforms can assume that standard broker authentication will work for the new endpoint(s). See [Extention Authentication](#extention-api-authentication) for more information.| +| adheres_to | string | A URI pointing to a specification detailing the implementation guidelines for the OpenAPI document hosted at the `discovery_url`. If present, must be a valid URI.| ``` { "dashboard_url": "http://example-dashboard.example.com/9189kdfsk0vfnku", - "operation": "task_10" + "operation": "task_10", + "extension_apis":[{ + "discovery_url": "http://example-openapi-doc.example.com/extentions", + "credentials":[{ + "tokenURL": "https://example.com/api/oauth/token" + }] + "adheres_to": "http://example-specification.example.com" + }] } ``` @@ -1422,3 +1440,21 @@ If the Platform encounters an internal error provisioning a Service Instance or Service Binding (for example, saving to the database fails), then it MUST at least send a single delete or unbind request to the Service Broker to prevent the creation of an orphan. + +## Extentions + +A Service Broker might want to extend the Service Broker API to include custom endpoints specific to their service. An example of this could be lifecycle management, (e.g. "Day Two Operations"), like Backup, Restore, Stop, Start, Restart and Pause. Extending the Service Broker API can be done on a per Service Instance basis, during provisioning. The 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. + +### OpenAPI Document + +To extend the API, the Service Broker MUST create an OpenAPI 3.0+ document describing the additional API endpoints and parameters. 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. + +### Extention API on Remote Servers + +Additional API endpoints MAY be executed on a remote server, however the OpenAPI document MUST include the servers `url` so that the Platform will know how to invoke the endpoint(s). If the server `context` parameter of the OpenAPI docuement is set to local host the Platform can assume the extention API endpoints are to be invoked using the Service Broker host and port. + +### Extention API Authentication + +The Service Broker MAY use the the same broker authentication method for invocation of extention endpoints by not providing credentials as part of a `extentions_api` object. If no credentials are present in an `extentions_api` object, the Platform can assume that the default broker authentication is required. + +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 docuement, (e.g. an OAuth Flow Object), and the appropriate credential(s), (e.g. bearer token), as part of the `extentions_api` object. If credentials are present in an `extentions_api` object, the Platform will need to verify the authentication method from the OpenAPI document. \ No newline at end of file From cf0ed7e82c2055feb4f4d8ee162aad0561370cf5 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Thu, 25 Jan 2018 17:42:57 -0500 Subject: [PATCH 02/29] add to toc --- spec.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 210e7d4b..82a405d3 100644 --- a/spec.md +++ b/spec.md @@ -26,6 +26,7 @@ - [Unbinding](#unbinding) - [Deprovisioning](#deprovisioning) - [Orphans](#orphans) + - [Extentions](#extentions) ## API Overview @@ -1457,4 +1458,4 @@ Additional API endpoints MAY be executed on a remote server, however the OpenAPI The Service Broker MAY use the the same broker authentication method for invocation of extention endpoints by not providing credentials as part of a `extentions_api` object. If no credentials are present in an `extentions_api` object, the Platform can assume that the default broker authentication is required. -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 docuement, (e.g. an OAuth Flow Object), and the appropriate credential(s), (e.g. bearer token), as part of the `extentions_api` object. If credentials are present in an `extentions_api` object, the Platform will need to verify the authentication method from the OpenAPI document. \ No newline at end of file +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 docuement, (e.g. an OAuth Flow Object), and the appropriate credential(s), (e.g. bearer token), as part of the `extentions_api` object. If credentials are present in an `extentions_api` object, the Platform will need to verify the authentication method from the OpenAPI document. From 5a0820c4b4430fac7f73078ccad7d20e7321b82d Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Thu, 25 Jan 2018 17:45:35 -0500 Subject: [PATCH 03/29] fix broken link --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 82a405d3..dcb1341b 100644 --- a/spec.md +++ b/spec.md @@ -842,7 +842,7 @@ 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. | -| extention_apis | array-of-objects | For extentions to the Service Broker API on a per Service Instance basis, Service Brokers MAY return one or more objects that desribe additional API endpoints via an OpenAPI document. See [Extention APIs Object](#extention-apis-object) for more information.| +| extention_apis | array-of-objects | For extentions to the Service Broker API on a per Service Instance basis, Service Brokers MAY return one or more objects that desribe additional API endpoints via an OpenAPI document. See [Extention APIs Object](#exention-apis-object) for more information.| ##### Exention APIs Object From 394d76e43fb839da9caaf50d5f6663ec3b88ae33 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Thu, 25 Jan 2018 17:47:24 -0500 Subject: [PATCH 04/29] spelling, links. --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index dcb1341b..fa30b667 100644 --- a/spec.md +++ b/spec.md @@ -846,7 +846,7 @@ For success responses, the following fields are defined: ##### Exention APIs Object -The `extention_api` object MAY be used to desribe any additional endpoint needed related to a Service Instance. An examples of this might include backup and restore endpoints for a database. If present, MUST return a `discovery_url`. See [Extentions](#extentions) for more information. +The `extention_apis` object MAY be used to desribe any additional endpoint needed related to a Service Instance. An examples of this might include backup and restore endpoints for a database. If present, MUST return a `discovery_url`. See [Extentions](#extentions) for more information. | Response field | Type | Description | | --- | --- | --- | @@ -1444,7 +1444,7 @@ the creation of an orphan. ## Extentions -A Service Broker might want to extend the Service Broker API to include custom endpoints specific to their service. An example of this could be lifecycle management, (e.g. "Day Two Operations"), like Backup, Restore, Stop, Start, Restart and Pause. Extending the Service Broker API can be done on a per Service Instance basis, during provisioning. The 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. +A Service Broker might want to extend the Service Broker API to include custom endpoints specific to their service. An example of this could be lifecycle management, (e.g. "Day Two Operations"), like Backup, Restore, Stop, Start, Restart and Pause. Extending the Service Broker API can be done on a per Service Instance basis, during provisioning. The 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. See [Provisioning](#provisioning) for more information on extentions on a per Service Instance basis. ### OpenAPI Document From 7242bc5167cb0dab474518c0143c92dc024c4e98 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Thu, 25 Jan 2018 18:41:06 -0500 Subject: [PATCH 05/29] Still can't spell. --- spec.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/spec.md b/spec.md index fa30b667..8e7aa25d 100644 --- a/spec.md +++ b/spec.md @@ -842,18 +842,19 @@ 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. | -| extention_apis | array-of-objects | For extentions to the Service Broker API on a per Service Instance basis, Service Brokers MAY return one or more objects that desribe additional API endpoints via an OpenAPI document. See [Extention APIs Object](#exention-apis-object) for more information.| +| extention_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 [Extention APIs Object](#extention-apis-object) for more information.| -##### Exention APIs Object +##### Extension APIs Object -The `extention_apis` object MAY be used to desribe any additional endpoint needed related to a Service Instance. An examples of this might include backup and restore endpoints for a database. If present, MUST return a `discovery_url`. See [Extentions](#extentions) for more information. +The `extension_apis` object MAY be used to describe any additional endpoint needed related to a Service Instance. An examples of this might include backup and restore endpoints for a database. If present, MUST return a `discovery_url`. See [Extensions](#extensions) for more information. | Response field | Type | Description | | --- | --- | --- | -| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extention(s) to the Service Instance including server location, endpoints, parameters and any other detail required for invocation. The location of the API extention endpoint(s) can be local to the Service Broker or on a remote server. The Platform MUST execute these API extentions on behalf of the client. MUST be a valid URI. See [OpenAPI](#openapi-document) for more information.| -| credentials | object | A Service Broker MAY return authentication details for running any of the extention API calls, especially for those running on remote servers. If not present, platforms can assume that standard broker authentication will work for the new endpoint(s). See [Extention Authentication](#extention-api-authentication) for more information.| +| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail required for invocation. The location of the API extension endpoint(s) can be local to the Service Broker or on a remote server. The Platform MUST execute these API extensions on behalf of the client. MUST be a valid URI. See [OpenAPI](#openapi-document) 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, platforms can assume that standard broker authentication will work for the new endpoint(s). See [Extension Authentication](#extension-api-authentication) for more information.| | adheres_to | string | A URI pointing to a specification detailing the implementation guidelines for the OpenAPI document hosted at the `discovery_url`. If present, must be a valid URI.| + ``` { "dashboard_url": "http://example-dashboard.example.com/9189kdfsk0vfnku", @@ -1442,20 +1443,20 @@ Service Binding (for example, saving to the database fails), then it MUST at least send a single delete or unbind request to the Service Broker to prevent the creation of an orphan. -## Extentions +## Extensions -A Service Broker might want to extend the Service Broker API to include custom endpoints specific to their service. An example of this could be lifecycle management, (e.g. "Day Two Operations"), like Backup, Restore, Stop, Start, Restart and Pause. Extending the Service Broker API can be done on a per Service Instance basis, during provisioning. The 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. See [Provisioning](#provisioning) for more information on extentions on a per Service Instance basis. +A Service Broker might want to extend the Service Broker API to include custom endpoints specific to their service. An example of this could be lifecycle management, (e.g. "Day Two Operations"), like Backup, Restore, Stop, Start, Restart and Pause. Extending the Service Broker API can be done on a per Service Instance basis, during provisioning. The 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. See [Provisioning](#provisioning) for more information on extensions on a per Service Instance basis. ### OpenAPI Document To extend the API, the Service Broker MUST create an OpenAPI 3.0+ document describing the additional API endpoints and parameters. 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. -### Extention API on Remote Servers +### Extension API on Remote Servers -Additional API endpoints MAY be executed on a remote server, however the OpenAPI document MUST include the servers `url` so that the Platform will know how to invoke the endpoint(s). If the server `context` parameter of the OpenAPI docuement is set to local host the Platform can assume the extention API endpoints are to be invoked using the Service Broker host and port. +Additional API endpoints MAY be executed on a remote server, however the OpenAPI document MUST include the servers `url` so that the Platform will know how to invoke the endpoint(s). If the server `context` parameter of the OpenAPI document is set to local host the Platform can assume the extension API endpoints are to be invoked using the Service Broker host and port. -### Extention API Authentication +### Extension API Authentication -The Service Broker MAY use the the same broker authentication method for invocation of extention endpoints by not providing credentials as part of a `extentions_api` object. If no credentials are present in an `extentions_api` object, the Platform can assume that the default broker authentication is required. +The Service Broker MAY use the the same broker authentication method for invocation of extension endpoints by not providing credentials as part of a `extensions_api` object. If no credentials are present in an `extensions_api` object, the Platform can assume that the default broker authentication is required. -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 docuement, (e.g. an OAuth Flow Object), and the appropriate credential(s), (e.g. bearer token), as part of the `extentions_api` object. If credentials are present in an `extentions_api` object, the Platform will need to verify the authentication method from the OpenAPI document. +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. If credentials are present in an `extensions_api` object, the Platform will need to verify the authentication method from the OpenAPI document. From f59f0775c6da676bcbe9cb78d982c9440f741425 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Thu, 25 Jan 2018 18:41:29 -0500 Subject: [PATCH 06/29] Update spec.md --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 8e7aa25d..ad0f12c7 100644 --- a/spec.md +++ b/spec.md @@ -26,7 +26,7 @@ - [Unbinding](#unbinding) - [Deprovisioning](#deprovisioning) - [Orphans](#orphans) - - [Extentions](#extentions) + - [Extensions](#extensions) ## API Overview From 914dc83d2bca1c3accc501dfb4c719bc17e11ecd Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Thu, 25 Jan 2018 18:43:12 -0500 Subject: [PATCH 07/29] Update spec.md --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index ad0f12c7..6ec68126 100644 --- a/spec.md +++ b/spec.md @@ -842,7 +842,7 @@ 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. | -| extention_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 [Extention APIs Object](#extention-apis-object) for more information.| +| 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 From f66a0604eca47e3b0d241b1f2904edf9587cf424 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Thu, 25 Jan 2018 18:44:00 -0500 Subject: [PATCH 08/29] Update spec.md --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 6ec68126..e5b0eae7 100644 --- a/spec.md +++ b/spec.md @@ -860,7 +860,7 @@ The `extension_apis` object MAY be used to describe any additional endpoint need "dashboard_url": "http://example-dashboard.example.com/9189kdfsk0vfnku", "operation": "task_10", "extension_apis":[{ - "discovery_url": "http://example-openapi-doc.example.com/extentions", + "discovery_url": "http://example-openapi-doc.example.com/extensions", "credentials":[{ "tokenURL": "https://example.com/api/oauth/token" }] From a400b538f999e2d22aced835c3b16df43b49299e Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Thu, 25 Jan 2018 19:18:44 -0500 Subject: [PATCH 09/29] Some minor changes to make ci happy. --- spec.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/spec.md b/spec.md index e5b0eae7..f855706e 100644 --- a/spec.md +++ b/spec.md @@ -842,7 +842,7 @@ 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 | 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 @@ -850,9 +850,9 @@ The `extension_apis` object MAY be used to describe any additional endpoint need | Response field | Type | Description | | --- | --- | --- | -| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail required for invocation. The location of the API extension endpoint(s) can be local to the Service Broker or on a remote server. The Platform MUST execute these API extensions on behalf of the client. MUST be a valid URI. See [OpenAPI](#openapi-document) 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, platforms can assume that standard broker authentication will work for the new endpoint(s). See [Extension Authentication](#extension-api-authentication) for more information.| -| adheres_to | string | A URI pointing to a specification detailing the implementation guidelines for the OpenAPI document hosted at the `discovery_url`. If present, must be a valid URI.| +| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail necessary for invocation. The location of the API extension endpoint(s) can be local to the Service Broker or on a remote server. The Platform MUST execute these API extensions on behalf of the client. MUST be a valid URI. See [OpenAPI](#openapi-document) 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, platforms can assume that standard broker authentication will work for the new endpoint(s). See [Extension Authentication](#extension-api-authentication) for more information. | +| adheres_to | string | A URI pointing to a specification detailing the implementation guidelines for the OpenAPI document hosted at the `discovery_url`. If present, MUST be a valid URI. | ``` @@ -1457,6 +1457,6 @@ Additional API endpoints MAY be executed on a remote server, however the OpenAPI ### Extension API Authentication -The Service Broker MAY use the the same broker authentication method for invocation of extension endpoints by not providing credentials as part of a `extensions_api` object. If no credentials are present in an `extensions_api` object, the Platform can assume that the default broker authentication is required. +The Service Broker MAY use the the same broker authentication method for invocation of extension endpoints by not providing credentials as part of a `extensions_api` object. If no credentials are present in an `extensions_api` object, the Platform can assume that the default broker authentication method is to be used. 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. If credentials are present in an `extensions_api` object, the Platform will need to verify the authentication method from the OpenAPI document. From 12a1a224d39ce022f5e71e1ee03a9fad5b371c1c Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Mon, 29 Jan 2018 18:42:14 -0500 Subject: [PATCH 10/29] addressing dougs comments --- spec.md | 402 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 199 insertions(+), 203 deletions(-) diff --git a/spec.md b/spec.md index f855706e..e8550ea0 100644 --- a/spec.md +++ b/spec.md @@ -26,7 +26,6 @@ - [Unbinding](#unbinding) - [Deprovisioning](#deprovisioning) - [Orphans](#orphans) - - [Extensions](#extensions) ## API Overview @@ -255,10 +254,10 @@ include additional fields within the response. When adding new fields, Service Brokers SHOULD use a unique prefix for the field names to reduce the chances of conflict with future specification defined fields. -| Response Field | Type | Description | -| --- | --- | --- | -| error | string | A single word in camel case that uniquely identifies the error condition. If present, MUST be a non-empty string. | -| description | string | A user-facing error message explaining why the request failed. If present, MUST be a non-empty string. | +| Response Field | Type | Description | +| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | +| error | string | A single word in camel case that uniquely identifies the error condition. If present, MUST be a non-empty string. | +| description | string | A user-facing error message explaining why the request failed. If present, MUST be a non-empty string. | ### Error Codes @@ -266,11 +265,11 @@ There are failure scenarios described throughout this specification for which the `error` field MUST contain a specific string. Service Broker authors MUST use these error codes for the specified failure scenarios. -| Error | Reason | Expected Action | -| --- | --- | --- | -| AsyncRequired | This request requires client support for asynchronous service operations. | The query parameter `accepts_incomplete=true` MUST be included the request. | +| Error | Reason | Expected Action | +| ---------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| AsyncRequired | This request requires client support for asynchronous service operations. | The query parameter `accepts_incomplete=true` MUST be included the request. | | ConcurrencyError | The Service Broker does not support concurrent requests that mutate the same resource. | Clients MUST wait until pending requests have completed for the specified resources. | -| RequiresApp | The request body is missing the `app_guid` field. | The `app_guid` MUST be included in the request body. | +| RequiresApp | The request body is missing the `app_guid` field. | The `app_guid` MUST be included in the request body. | ## Catalog Management @@ -314,8 +313,8 @@ Broker API. The following HTTP Headers are defined for this operation: -| Header | Type | Description | -| --- | --- | --- | +| Header | Type | Description | +| --------------------------------------- | --------- | ----------------------------------------------------------------------------------------- | | X-Broker-API-Version* | string | See [API Version Header](#api-version-header). | \* Headers with an asterisk are REQUIRED. @@ -327,9 +326,9 @@ $ curl http://username:password@service-broker-url/v2/catalog -H "X-Broker-API-V ### Response -| Status Code | Description | -| --- | --- | -| 200 OK | MUST be returned upon successful processing of this request. The expected response body is below. | +| Status Code | Description | +| ----------- | ------------------------------------------------------------------------------------------------- | +| 200 OK | MUST be returned upon successful processing of this request. The expected response body is below. | #### Body @@ -344,26 +343,26 @@ the use of CLI-unfriendly strings that might cause problems for command line parsers (or that are not very meaningful to users), such as `-`. It is therefore RECOMMENDED that implementations avoid such strings. -| Response field | Type | Description | -| --- | --- | --- | -| services* | array-of-service-objects | Schema of service objects defined below. MAY be empty. | +| Response field | Type | Description | +| -------------- | ------------------------ | ------------------------------------------------------ | +| services* | array-of-service-objects | Schema of service objects defined below. MAY be empty. | \* Fields with an asterisk are REQUIRED. ##### Service Objects -| Response field | Type | Description | -| --- | --- | --- | -| name* | string | A CLI-friendly name of the service. MUST only contain lowercase characters, numbers and hyphens (no spaces). MUST be unique across all service objects returned in this response. MUST be a non-empty string. | -| id* | string | An identifier used to correlate this service in future requests to the Service Broker. This MUST be globally unique. MUST be a non-empty string. Using a GUID is RECOMMENDED. | -| description* | string | A short description of the service. MUST be a non-empty string. | -| tags | array-of-strings | Tags provide a flexible mechanism to expose a classification, attribute, or base technology of a service, enabling equivalent services to be swapped out without changes to dependent logic in applications, buildpacks, or other services. E.g. mysql, relational, redis, key-value, caching, messaging, amqp. | -| requires | array-of-strings | A list of permissions that the user would have to give the service, if they provision it. The only permissions currently supported are `syslog_drain`, `route_forwarding` and `volume_mount`. | -| bindable* | boolean | Specifies whether Service Instances of the service can be bound to applications. This specifies the default for all plans of this service. Plans can override this field (see [Plan Object](#plan-object)). | -| metadata | object | An opaque object of metadata for a Service Offering. Controller treats this as a blob. Note that there are [conventions](profile.md#service-metadata) in existing Service Brokers and controllers for fields that aid in the display of catalog data. | -| [dashboard_client](#dashboard-client-object) | object | Contains the data necessary to activate the Dashboard SSO feature for this service. | -| plan_updateable | boolean | Whether the service supports upgrade/downgrade for some plans. Please note that the misspelling of the attribute `plan_updatable` as `plan_updateable` was done by mistake. We have opted to keep that misspelling instead of fixing it and thus breaking backward compatibility. Defaults to false. | -| [plans*](#plan-object) | array-of-objects | A list of plans for this service, schema is defined below. MUST contain at least one plan. | +| Response field | Type | Description | +| -------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| name* | string | A CLI-friendly name of the service. MUST only contain lowercase characters, numbers and hyphens (no spaces). MUST be unique across all service objects returned in this response. MUST be a non-empty string. | +| id* | string | An identifier used to correlate this service in future requests to the Service Broker. This MUST be globally unique. MUST be a non-empty string. Using a GUID is RECOMMENDED. | +| description* | string | A short description of the service. MUST be a non-empty string. | +| tags | array-of-strings | Tags provide a flexible mechanism to expose a classification, attribute, or base technology of a service, enabling equivalent services to be swapped out without changes to dependent logic in applications, buildpacks, or other services. E.g. mysql, relational, redis, key-value, caching, messaging, amqp. | +| requires | array-of-strings | A list of permissions that the user would have to give the service, if they provision it. The only permissions currently supported are `syslog_drain`, `route_forwarding` and `volume_mount`. | +| bindable* | boolean | Specifies whether Service Instances of the service can be bound to applications. This specifies the default for all plans of this service. Plans can override this field (see [Plan Object](#plan-object)). | +| metadata | object | An opaque object of metadata for a Service Offering. Controller treats this as a blob. Note that there are [conventions](profile.md#service-metadata) in existing Service Brokers and controllers for fields that aid in the display of catalog data. | +| [dashboard_client](#dashboard-client-object) | object | Contains the data necessary to activate the Dashboard SSO feature for this service. | +| plan_updateable | boolean | Whether the service supports upgrade/downgrade for some plans. Please note that the misspelling of the attribute `plan_updatable` as `plan_updateable` was done by mistake. We have opted to keep that misspelling instead of fixing it and thus breaking backward compatibility. Defaults to false. | +| [plans*](#plan-object) | array-of-objects | A list of plans for this service, schema is defined below. MUST contain at least one plan. | \* Fields with an asterisk are REQUIRED. @@ -378,52 +377,52 @@ how Platforms might expose these values to their users. ##### Dashboard Client Object -| Response field | Type | Description | -| --- | --- | --- | -| id | string | The id of the Oauth client that the dashboard will use. If present, MUST be a non-empty string. | -| secret | string | A secret for the dashboard client. If present, MUST be a non-empty string. | -| redirect_uri | string | A URI for the service dashboard. Validated by the OAuth token server when the dashboard requests a token. | +| Response field | Type | Description | +| -------------- | ------ | --------------------------------------------------------------------------------------------------------- | +| id | string | The id of the Oauth client that the dashboard will use. If present, MUST be a non-empty string. | +| secret | string | A secret for the dashboard client. If present, MUST be a non-empty string. | +| redirect_uri | string | A URI for the service dashboard. Validated by the OAuth token server when the dashboard requests a token. | ##### Plan Object -| Response field | Type | Description | -| --- | --- | --- | -| id* | string | An identifier used to correlate this plan in future requests to the Service Broker. This MUST be globally unique. MUST be a non-empty string. Using a GUID is RECOMMENDED. | -| name* | string | The CLI-friendly name of the plan. MUST only contain lowercase characters, numbers and hyphens (no spaces). MUST be unique within the service. MUST be a non-empty string. | -| description* | string | A short description of the plan. MUST be a non-empty string. | -| metadata | object | An opaque object of metadata for a Service Plan. Controller treats this as a blob. Note that there are [conventions](profile.md#service-metadata) in existing Service Brokers and controllers for fields that aid in the display of catalog data. | -| free | boolean | When false, Service Instances of this plan have a cost. The default is true. | -| bindable | boolean | Specifies whether Service Instances of the Service Plan can be bound to applications. This field is OPTIONAL. If specified, this takes precedence over the `bindable` attribute of the service. If not specified, the default is derived from the service. | -| [schemas](#schema-object) | object | Schema definitions for Service Instances and bindings for the plan. | +| Response field | Type | Description | +| ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| id* | string | An identifier used to correlate this plan in future requests to the Service Broker. This MUST be globally unique. MUST be a non-empty string. Using a GUID is RECOMMENDED. | +| name* | string | The CLI-friendly name of the plan. MUST only contain lowercase characters, numbers and hyphens (no spaces). MUST be unique within the service. MUST be a non-empty string. | +| description* | string | A short description of the plan. MUST be a non-empty string. | +| metadata | object | An opaque object of metadata for a Service Plan. Controller treats this as a blob. Note that there are [conventions](profile.md#service-metadata) in existing Service Brokers and controllers for fields that aid in the display of catalog data. | +| free | boolean | When false, Service Instances of this plan have a cost. The default is true. | +| bindable | boolean | Specifies whether Service Instances of the Service Plan can be bound to applications. This field is OPTIONAL. If specified, this takes precedence over the `bindable` attribute of the service. If not specified, the default is derived from the service. | +| [schemas](#schema-object) | object | Schema definitions for Service Instances and bindings for the plan. | \* Fields with an asterisk are REQUIRED. ##### Schema Object -| Response field | Type | Description | -| --- | --- | --- | -| [service_instance](#service-instance-object) | object | The schema definitions for creating and updating a Service Instance. | -| [service_binding](#service-binding-object) | object | The schema definition for creating a Service Binding. Used only if the Service Plan is bindable. | +| Response field | Type | Description | +| -------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | +| [service_instance](#service-instance-object) | object | The schema definitions for creating and updating a Service Instance. | +| [service_binding](#service-binding-object) | object | The schema definition for creating a Service Binding. Used only if the Service Plan is bindable. | ##### Service Instance Object -| Response field | Type | Description | -| --- | --- | --- | +| Response field | Type | Description | +| ---------------------------------- | ------ | ------------------------------------------------------ | | [create](#input-parameters-object) | object | The schema definition for creating a Service Instance. | | [update](#input-parameters-object) | object | The schema definition for updating a Service Instance. | ##### Service Binding Object -| Response field | Type | Description | -| --- | --- | --- | +| Response field | Type | Description | +| ---------------------------------- | ------ | ----------------------------------------------------- | | [create](#input-parameters-object) | object | The schema definition for creating a Service Binding. | ##### Input Parameters Object -| Response field | Type | Description | -| --- | --- | --- | -| parameters | JSON schema object | The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object. | +| Response field | Type | Description | +| -------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- | +| parameters | JSON schema object | The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object. | The following rules apply if `parameters` is included anywhere in the catalog: * Platforms MUST support at least @@ -671,11 +670,11 @@ to provide additional detail for users about the progress of the operation. The request provides these query string parameters as useful hints for Service Brokers. -| Query-String Field | Type | Description | -| --- | --- | --- | -| service_id | string | If present, it MUST be the ID of the service being used. | -| plan_id | string | If present, it MUST be the ID of the plan for the service being use. | -| operation | string | A Service Broker-provided identifier for the operation. When a value for `operation` is included with asynchronous responses for [Provision](#provisioning), [Update](#updating-a-service-instance), and [Deprovision](#deprovisioning) requests, the Platform MUST provide the same value using this query parameter as a percent-encoded string. If present, MUST be a non-empty string. | +| Query-String Field | Type | Description | +| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| service_id | string | If present, it MUST be the ID of the service being used. | +| plan_id | string | If present, it MUST be the ID of the plan for the service being use. | +| operation | string | A Service Broker-provided identifier for the operation. When a value for `operation` is included with asynchronous responses for [Provision](#provisioning), [Update](#updating-a-service-instance), and [Deprovision](#deprovisioning) requests, the Platform MUST provide the same value using this query parameter as a percent-encoded string. If present, MUST be a non-empty string. | Note: Although the request query parameters `service_id` and `plan_id` are not mandatory, the Platform SHOULD include them on all `last_operation` requests @@ -698,11 +697,11 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc ### Response -| Status Code | Description | -| --- | --- | -| 200 OK | MUST be returned upon successful processing of this request. The expected response body is below. | -| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | -| 410 Gone | Appropriate only for asynchronous delete operations. The Platform MUST consider this response a success and forget about the resource. The expected response body is `{}`. Returning this while the Platform is polling for create or update operations SHOULD be interpreted as an invalid response and the Platform SHOULD continue polling. | +| Status Code | Description | +| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 OK | MUST be returned upon successful processing of this request. The expected response body is below. | +| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | +| 410 Gone | Appropriate only for asynchronous delete operations. The Platform MUST consider this response a success and forget about the resource. The expected response body is `{}`. Returning this while the Platform is polling for create or update operations SHOULD be interpreted as an invalid response and the Platform SHOULD continue polling. | Responses with any other status code SHOULD be interpreted as an error or invalid response. The Platform SHOULD continue polling until the Service Broker @@ -713,10 +712,10 @@ returns a valid response or the For success responses, the following fields are defined: -| 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"` MUST cause the Platform to cease polling. | -| description | string | A user-facing message displayed to the Platform API client. Can be used to tell the user details about the status of the operation. If present, MUST be a non-empty string. | +| 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"` MUST cause the Platform to cease polling. | +| description | string | A user-facing message displayed to the Platform API client. Can be used to tell the user details about the status of the operation. If present, MUST be a non-empty string. | \* Fields with an asterisk are REQUIRED. @@ -757,30 +756,30 @@ This ID will be used for future requests (bind and deprovision), so the Service Broker will use it to correlate the resource it creates. #### Parameters -| Parameter name | Type | Description | -| --- | --- | --- | +| Parameter name | Type | Description | +| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accepts_incomplete | boolean | A value of true indicates that the Platform and its clients support asynchronous Service Broker operations. If this parameter is not included in the request, and the Service Broker can only provision a Service Instance of the requested plan asynchronously, the Service Broker MUST reject the request with a `422 Unprocessable Entity` as described below. | #### Headers The following HTTP Headers are defined for this operation: -| Header | Type | Description | -| --- | --- | --- | -| X-Broker-API-Version* | string | See [API Version Header](#api-version-header). | +| Header | Type | Description | +| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| X-Broker-API-Version* | string | See [API Version Header](#api-version-header). | | X-Broker-API-Originating-Identity | string | See [Originating Identity](#originating-identity). | \* Headers with an asterisk are REQUIRED. #### Body -| Request field | Type | Description | -| --- | --- | --- | -| service_id* | string | MUST be the ID of a service from the catalog for this Service Broker. | -| plan_id* | string | MUST be the ID of a plan from the service that has been requested. | -| context | object | Platform specific contextual information under which the Service Instance is to be provisioned. Although most Service Brokers will not use this field, it could be helpful in determining data placement or applying custom business rules. `context` will replace `organization_guid` and `space_guid` in future versions of the specification - in the interim both SHOULD be used to ensure interoperability with old and new implementations. | -| organization_guid* | string | Deprecated in favor of `context`. The Platform GUID for the organization under which the Service Instance is to be provisioned. Although most Service Brokers will not use this field, it might be helpful for executing operations on a user's behalf. MUST be a non-empty string. | -| space_guid* | string | Deprecated in favor of `context`. The identifier for the project space within the Platform organization. Although most Service Brokers will not use this field, it might be helpful for executing operations on a user's behalf. MUST be a non-empty string. | -| parameters | object | Configuration options for the Service Instance. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. | +| Request field | Type | Description | +| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| service_id* | string | MUST be the ID of a service from the catalog for this Service Broker. | +| plan_id* | string | MUST be the ID of a plan from the service that has been requested. | +| context | object | Platform specific contextual information under which the Service Instance is to be provisioned. Although most Service Brokers will not use this field, it could be helpful in determining data placement or applying custom business rules. `context` will replace `organization_guid` and `space_guid` in future versions of the specification - in the interim both SHOULD be used to ensure interoperability with old and new implementations. | +| organization_guid* | string | Deprecated in favor of `context`. The Platform GUID for the organization under which the Service Instance is to be provisioned. Although most Service Brokers will not use this field, it might be helpful for executing operations on a user's behalf. MUST be a non-empty string. | +| space_guid* | string | Deprecated in favor of `context`. The identifier for the project space within the Platform organization. Although most Service Brokers will not use this field, it might be helpful for executing operations on a user's behalf. MUST be a non-empty string. | +| parameters | object | Configuration options for the Service Instance. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. | \* Fields with an asterisk are REQUIRED. @@ -821,13 +820,13 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc ### Response -| Status Code | Description | -| --- | --- | -| 200 OK | MUST be returned if the Service Instance already exists, is fully provisioned, and the requested parameters are identical to the existing Service Instance. The expected response body is below. | -| 201 Created | MUST be returned if the Service Instance was provisioned as a result of this request. The expected response body is below. | -| 202 Accepted | MUST be returned if the Service Instance provisioning is in progress. This triggers the Platform to poll the [Service Instance Last Operation Endpoint](#polling-last-operation) for operation status. Note that a re-sent `PUT` request MUST return a `202 Accepted`, not a `200 OK`, if the Service Instance is not yet fully provisioned. | -| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | -| 409 Conflict | MUST be returned if a Service Instance with the same id already exists but with different attributes. | +| Status Code | Description | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 OK | MUST be returned if the Service Instance already exists, is fully provisioned, and the requested parameters are identical to the existing Service Instance. The expected response body is below. | +| 201 Created | MUST be returned if the Service Instance was provisioned as a result of this request. The expected response body is below. | +| 202 Accepted | MUST be returned if the Service Instance provisioning is in progress. This triggers the Platform to poll the [Service Instance Last Operation Endpoint](#polling-last-operation) for operation status. Note that a re-sent `PUT` request MUST return a `202 Accepted`, not a `200 OK`, if the Service Instance is not yet fully provisioned. | +| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | +| 409 Conflict | MUST be returned if a Service Instance with the same id already exists but with different attributes. | | 422 Unprocessable Entity | MUST be returned if the Service Broker only supports asynchronous provisioning for the requested plan and the request did not include `?accepts_incomplete=true`. The response body MUST contain a response body containing error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. | Responses with any other status code will be interpreted as a failure and a @@ -838,21 +837,36 @@ being created on the Service Broker. For success responses, the following fields are defined: -| 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 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. | +| 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 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 needed related to a Service Instance. An examples of this might include backup and restore endpoints for a database. If present, MUST return a `discovery_url`. See [Extensions](#extensions) for more information. +The `extension_apis` object MAY be used to describe any additional endpoint +needed related to a Service Instance. An example of this could be lifecycle +management, (e.g. "Day Two Operations"), like Backup, Restore, Stop, Start, +Restart and Pause. -| Response field | Type | Description | -| --- | --- | --- | -| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail necessary for invocation. The location of the API extension endpoint(s) can be local to the Service Broker or on a remote server. The Platform MUST execute these API extensions on behalf of the client. MUST be a valid URI. See [OpenAPI](#openapi-document) 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, platforms can assume that standard broker authentication will work for the new endpoint(s). See [Extension Authentication](#extension-api-authentication) for more information. | -| adheres_to | string | A URI pointing to a specification detailing the implementation guidelines for the OpenAPI document hosted at the `discovery_url`. If present, MUST be a valid URI. | +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 the servers `url` so that the Platform will know how to +invoke the endpoint(s). If the server `context` parameter of the OpenAPI +document is set to localhost the Platform can assume the extension API endpoints +are to be invoked using the Service Broker host and port. + +| Response field | Type | Description | +| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| discovery_url* | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail required 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. 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. | ``` @@ -863,7 +877,7 @@ The `extension_apis` object MAY be used to describe any additional endpoint need "discovery_url": "http://example-openapi-doc.example.com/extensions", "credentials":[{ "tokenURL": "https://example.com/api/oauth/token" - }] + }], "adheres_to": "http://example-specification.example.com" }] } @@ -896,8 +910,8 @@ error message in response. `:instance_id` MUST be the ID a previously provisioned Service Instance. #### Parameters -| Parameter name | Type | Description | -| --- | --- | --- | +| Parameter name | Type | Description | +| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accepts_incomplete | boolean | A value of true indicates that the Platform and its clients support asynchronous Service Broker operations. If this parameter is not included in the request, and the Service Broker can only provision a Service Instance of the requested plan asynchronously, the Service Broker SHOULD reject the request with a `422 Unprocessable Entity` as described below. | #### Headers @@ -913,24 +927,24 @@ The following HTTP Headers are defined for this operation: #### Body -| Request Field | Type | Description | -| --- | --- | --- | -| context | object | Contextual data under which the Service Instance is created. | -| service_id* | string | MUST be the ID of a service from the catalog for this Service Broker. | -| plan_id | string | If present, MUST be the ID of a plan from the service that has been requested. If this field is not present in the request message, then the Service Broker MUST NOT change the plan of the instance as a result of this request. | -| parameters | object | Configuration options for the Service Instance. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. See "Note" below. | -| [previous_values](#previous-values-object) | object | Information about the Service Instance prior to the update. | +| Request Field | Type | Description | +| ------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| context | object | Contextual data under which the Service Instance is created. | +| service_id* | string | MUST be the ID of a service from the catalog for this Service Broker. | +| plan_id | string | If present, MUST be the ID of a plan from the service that has been requested. If this field is not present in the request message, then the Service Broker MUST NOT change the plan of the instance as a result of this request. | +| parameters | object | Configuration options for the Service Instance. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. See "Note" below. | +| [previous_values](#previous-values-object) | object | Information about the Service Instance prior to the update. | \* Fields with an asterisk are REQUIRED. ##### Previous Values Object -| Request Field | Type | Description | -| --- | --- | --- | -| service_id | string | Deprecated; determined to be unnecessary as the value is immutable. If present, it MUST be the ID of the service for the Service Instance. | -| plan_id | string | If present, it MUST be the ID of the plan prior to the update. | +| Request Field | Type | Description | +| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| service_id | string | Deprecated; determined to be unnecessary as the value is immutable. If present, it MUST be the ID of the service for the Service Instance. | +| plan_id | string | If present, it MUST be the ID of the plan prior to the update. | | organization_id | string | Deprecated as it was redundant information. Organization for the Service Instance MUST be provided by Platforms in the top-level field `context`. If present, it MUST be the ID of the organization specified for the Service Instance. | -| space_id | string | Deprecated as it was redundant information. Space for the Service Instance MUST be provided by Platforms in the top-level field `context`. If present, it MUST be the ID of the space specified for the Service Instance. | +| space_id | string | Deprecated as it was redundant information. Space for the Service Instance MUST be provided by Platforms in the top-level field `context`. If present, it MUST be the ID of the space specified for the Service Instance. | Note: The `parameters` specified are expected to be the values specified by an end-user. Whether the user chooses to include the complete set of @@ -994,11 +1008,11 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc ### Response -| Status Code | Description | -| --- | --- | -| 200 OK | MUST be returned if the request's changes have been applied. The expected response body is `{}`. | -| 202 Accepted | MUST be returned if the Service Instance update is in progress. This triggers the Platform to poll the [Last Operation](#polling-last-operation) for operation status. Note that a re-sent `PATCH` request MUST return a `202 Accepted`, not a `200 OK`, if the requested update has not yet completed. | -| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | +| Status Code | Description | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 OK | MUST be returned if the request's changes have been applied. The expected response body is `{}`. | +| 202 Accepted | MUST be returned if the Service Instance update is in progress. This triggers the Platform to poll the [Last Operation](#polling-last-operation) for operation status. Note that a re-sent `PATCH` request MUST return a `202 Accepted`, not a `200 OK`, if the requested update has not yet completed. | +| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | | 422 Unprocessable entity | MUST be returned if the requested change is not supported or if the request cannot currently be fulfilled due to the state of the Service Instance (e.g. Service Instance utilization is over the quota of the requested plan). Additionally, a `422 Unprocessable Entity` can also be returned if the Service Broker only supports asynchronous update for the requested plan and the request did not include `?accepts_incomplete=true`; in this case the response body MUST contain a error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. | Responses with any other status code will be interpreted as a failure. @@ -1007,9 +1021,9 @@ Responses with any other status code will be interpreted as a failure. For success responses, the following fields are defined: -| Response field | Type | Description | -| --- | --- | --- | -| 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. | +| Response field | Type | Description | +| ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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. | ``` { @@ -1113,14 +1127,14 @@ The following HTTP Headers are defined for this operation: #### Body -| Request Field | Type | Description | -| --- | --- | --- | -| context | object | Contextual data under which the Service Binding is created. | -| service_id* | string | MUST be the ID of the service that is being used. | -| plan_id* | string | MUST be the ID of the plan from the service that is being used. | -| app_guid | string | Deprecated in favor of `bind_resource.app_guid`. GUID of an application associated with the binding to be created. If present, MUST be a non-empty string. | +| Request Field | Type | Description | +| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| context | object | Contextual data under which the Service Binding is created. | +| service_id* | string | MUST be the ID of the service that is being used. | +| plan_id* | string | MUST be the ID of the plan from the service that is being used. | +| app_guid | string | Deprecated in favor of `bind_resource.app_guid`. GUID of an application associated with the binding to be created. If present, MUST be a non-empty string. | | bind_resource | object | A JSON object that contains data for Platform resources associated with the binding to be created. See [Bind Resource Object](#bind-resource-object) for more information. | -| parameters | object | Configuration options for the Service Binding. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. | +| parameters | object | Configuration options for the Service Binding. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. | \* Fields with an asterisk are REQUIRED. @@ -1134,10 +1148,10 @@ request, therefore the `bind_resource` and its fields are OPTIONAL. Below are some common fields that MAY be used. Platforms MAY choose to add additional ones as needed. -| Request Field | Type | Description | -| --- | --- | --- | -| app_guid | string | GUID of an application associated with the binding. For [credentials](#types-of-binding) bindings. MUST be unique within the scope of the Platform. | -| route | string | URL of the application to be intermediated. For [route services](#route-services) bindings. | +| Request Field | Type | Description | +| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| app_guid | string | GUID of an application associated with the binding. For [credentials](#types-of-binding) bindings. MUST be unique within the scope of the Platform. | +| route | string | URL of the application to be intermediated. For [route services](#route-services) bindings. | `app_guid` represents the scope to which the binding will apply within the Platform. For example, in Cloud Foundry it might map to an "application" @@ -1185,12 +1199,12 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc ### Response -| Status Code | Description | -| --- | --- | -| 200 OK | MUST be returned if the binding already exists and the requested parameters are identical to the existing binding. The expected response body is below. | -| 201 Created | MUST be returned if the binding was created as a result of this request. The expected response body is below. | -| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | -| 409 Conflict | MUST be returned if a Service Binding with the same id, for the same Service Instance, already exists but with different parameters. | +| Status Code | Description | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 OK | MUST be returned if the binding already exists and the requested parameters are identical to the existing binding. The expected response body is below. | +| 201 Created | MUST be returned if the binding was created as a result of this request. The expected response body is below. | +| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | +| 409 Conflict | MUST be returned if a Service Binding with the same id, for the same Service Instance, already exists but with different parameters. | | 422 Unprocessable Entity | MUST be returned if the Service Broker requires that `app_guid` be included in the request body. The response body MUST contain error code `"RequiresApp"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service supports generation of credentials through binding an application only."`. Additionally, if the Service Broker rejects the request due to a concurrent request to create a binding for the same Service Instance, then this error MUST be returned (see [Blocking Operations](#blocking-operations)). | Responses with any other status code will be interpreted as a failure and an @@ -1201,22 +1215,22 @@ created on the Service Broker. For success responses, the following fields are defined: -| Response Field | Type | Description | -| --- | --- | --- | -| credentials | object | A free-form hash of credentials that can be used by applications or users to access the service. | -| syslog_drain_url | string | A URL to which logs MUST be streamed. `"requires":["syslog_drain"]` MUST be declared in the [Catalog](#catalog-management) endpoint or the Platform MUST consider the response invalid. | -| route_service_url | string | A URL to which the Platform MUST proxy requests for the address sent with `bind_resource.route` in the request body. `"requires":["route_forwarding"]` MUST be declared in the [Catalog](#catalog-management) endpoint or the Platform can consider the response invalid. | -| volume_mounts | array-of-objects | An array of configuration for remote storage devices to be mounted into an application container filesystem. `"requires":["volume_mount"]` MUST be declared in the [Catalog](#catalog-management) endpoint or the Platform can consider the response invalid. | +| Response Field | Type | Description | +| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| credentials | object | A free-form hash of credentials that can be used by applications or users to access the service. | +| syslog_drain_url | string | A URL to which logs MUST be streamed. `"requires":["syslog_drain"]` MUST be declared in the [Catalog](#catalog-management) endpoint or the Platform MUST consider the response invalid. | +| route_service_url | string | A URL to which the Platform MUST proxy requests for the address sent with `bind_resource.route` in the request body. `"requires":["route_forwarding"]` MUST be declared in the [Catalog](#catalog-management) endpoint or the Platform can consider the response invalid. | +| volume_mounts | array-of-objects | An array of configuration for remote storage devices to be mounted into an application container filesystem. `"requires":["volume_mount"]` MUST be declared in the [Catalog](#catalog-management) endpoint or the Platform can consider the response invalid. | ##### Volume Mounts Object -| Response Field | Type | Description | -| --- | --- | --- | -| driver* | string | Name of the volume driver plugin which manages the device. | -| container_dir* | string | The path in the application container onto which the volume will be mounted. This specification does not mandate what action the Platform is to take if the path specified already exists in the container. | -| mode* | string | "r" to mount the volume read-only or "rw" to mount it read-write. | -| device_type* | string | A string specifying the type of device to mount. Currently the only supported value is "shared". | -| device* | device-object | Device object containing device_type specific details. Currently only shared devices are supported. | +| Response Field | Type | Description | +| -------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| driver* | string | Name of the volume driver plugin which manages the device. | +| container_dir* | string | The path in the application container onto which the volume will be mounted. This specification does not mandate what action the Platform is to take if the path specified already exists in the container. | +| mode* | string | "r" to mount the volume read-only or "rw" to mount it read-write. | +| device_type* | string | A string specifying the type of device to mount. Currently the only supported value is "shared". | +| device* | device-object | Device object containing device_type specific details. Currently only shared devices are supported. | \* Fields with an asterisk are REQUIRED. @@ -1225,9 +1239,9 @@ For success responses, the following fields are defined: Currently only shared devices are supported; a distributed file system which can be mounted on all app instances simultaneously. -| Field | Type | Description | -| --- | --- | --- | -| volume_id* | string | ID of the shared volume to mount on every app instance. | +| Field | Type | Description | +| ------------ | ------ | --------------------------------------------------------------------------- | +| volume_id* | string | ID of the shared volume to mount on every app instance. | | mount_config | object | Configuration object to be passed to the driver when the volume is mounted. | \* Fields with an asterisk are REQUIRED. @@ -1288,10 +1302,10 @@ Service Instance. The request provides these query string parameters as useful hints for Service Brokers. -| Query-String Field | Type | Description | -| --- | --- | --- | -| service_id* | string | MUST be the ID of the service associated with the binding being deleted. | -| plan_id* | string | MUST be the ID of the plan associated with the binding being deleted. | +| Query-String Field | Type | Description | +| ------------------ | ------ | ------------------------------------------------------------------------ | +| service_id* | string | MUST be the ID of the service associated with the binding being deleted. | +| plan_id* | string | MUST be the ID of the plan associated with the binding being deleted. | \* Query parameters with an asterisk are REQUIRED. @@ -1315,11 +1329,11 @@ $ curl 'http://username:password@service-broker-url/v2/service_instances/:instan ### Response -| Status Code | Description | -| --- | --- | -| 200 OK | MUST be returned if the binding was deleted as a result of this request. The expected response body is `{}`. | -| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | -| 410 Gone | MUST be returned if the binding does not exist. The expected response body is `{}`. | +| Status Code | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------ | +| 200 OK | MUST be returned if the binding was deleted as a result of this request. The expected response body is `{}`. | +| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | +| 410 Gone | MUST be returned if the binding does not exist. The expected response body is `{}`. | Responses with any other status code will be interpreted as a failure and the Platform MUST continue to remember the Service Binding. @@ -1353,10 +1367,10 @@ The request provides these query string parameters as useful hints for Service Brokers. -| Query-String Field | Type | Description | -| --- | --- | --- | -| service_id* | string | MUST be the ID of the Service Instance being deleted. | -| plan_id* | string | MUST be the ID of the plan associated with the Service Instance being deleted. | +| Query-String Field | Type | Description | +| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| service_id* | string | MUST be the ID of the Service Instance being deleted. | +| plan_id* | string | MUST be the ID of the plan associated with the Service Instance being deleted. | | accepts_incomplete | boolean | A value of true indicates that both the Platform and the requesting client support asynchronous deprovisioning. If this parameter is not included in the request, and the Service Broker can only deprovision a Service Instance of the requested plan asynchronously, the Service Broker MUST reject the request with a `422 Unprocessable Entity` as described below. | \* Query parameters with an asterisk are REQUIRED. @@ -1380,12 +1394,12 @@ $ curl 'http://username:password@service-broker-url/v2/service_instances/:instan ### Response -| Status Code | Description | -| --- | --- | -| 200 OK | MUST be returned if the Service Instance was deleted as a result of this request. The expected response body is `{}`. | -| 202 Accepted | MUST be returned if the Service Instance deletion is in progress. This triggers the Platform to poll the [Service Instance Last Operation Endpoint](#polling-last-operation) for operation status. Note that a re-sent `DELETE` request MUST return a `202 Accepted`, not a `200 OK`, if the delete request has not completed yet. | -| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | -| 410 Gone | MUST be returned if the Service Instance does not exist. | +| Status Code | Description | +| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 200 OK | MUST be returned if the Service Instance was deleted as a result of this request. The expected response body is `{}`. | +| 202 Accepted | MUST be returned if the Service Instance deletion is in progress. This triggers the Platform to poll the [Service Instance Last Operation Endpoint](#polling-last-operation) for operation status. Note that a re-sent `DELETE` request MUST return a `202 Accepted`, not a `200 OK`, if the delete request has not completed yet. | +| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | +| 410 Gone | MUST be returned if the Service Instance does not exist. | | 422 Unprocessable Entity | MUST be returned if the Service Broker only supports asynchronous deprovisioning for the requested plan and the request did not include `?accepts_incomplete=true`. The response body MUST contain error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. | Responses with any other status code will be interpreted as a failure and the @@ -1427,36 +1441,18 @@ success. Platforms SHOULD initiate orphan mitigation in the following scenarios: | Status code of Service Broker response | Platform interpretation of response | Platform initiates orphan mitigation? | -| --- | --- | --- | -| 200 | Success | No | -| 200 with malformed response | Failure | No | -| 201 | Success | No | -| 201 with malformed response | Failure | Yes | -| All other 2xx | Failure | Yes | -| 408 | Timeout failure | Yes | -| All other 4xx | Request rejected | No | -| 5xx | Service Broker error | Yes | -| Timeout | Failure | Yes | +| -------------------------------------- | ----------------------------------- | ------------------------------------- | +| 200 | Success | No | +| 200 with malformed response | Failure | No | +| 201 | Success | No | +| 201 with malformed response | Failure | Yes | +| All other 2xx | Failure | Yes | +| 408 | Timeout failure | Yes | +| All other 4xx | Request rejected | No | +| 5xx | Service Broker error | Yes | +| Timeout | Failure | Yes | If the Platform encounters an internal error provisioning a Service Instance or Service Binding (for example, saving to the database fails), then it MUST at least send a single delete or unbind request to the Service Broker to prevent -the creation of an orphan. - -## Extensions - -A Service Broker might want to extend the Service Broker API to include custom endpoints specific to their service. An example of this could be lifecycle management, (e.g. "Day Two Operations"), like Backup, Restore, Stop, Start, Restart and Pause. Extending the Service Broker API can be done on a per Service Instance basis, during provisioning. The 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. See [Provisioning](#provisioning) for more information on extensions on a per Service Instance basis. - -### OpenAPI Document - -To extend the API, the Service Broker MUST create an OpenAPI 3.0+ document describing the additional API endpoints and parameters. 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. - -### Extension API on Remote Servers - -Additional API endpoints MAY be executed on a remote server, however the OpenAPI document MUST include the servers `url` so that the Platform will know how to invoke the endpoint(s). If the server `context` parameter of the OpenAPI document is set to local host the Platform can assume the extension API endpoints are to be invoked using the Service Broker host and port. - -### Extension API Authentication - -The Service Broker MAY use the the same broker authentication method for invocation of extension endpoints by not providing credentials as part of a `extensions_api` object. If no credentials are present in an `extensions_api` object, the Platform can assume that the default broker authentication method is to be used. - -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. If credentials are present in an `extensions_api` object, the Platform will need to verify the authentication method from the OpenAPI document. +the creation of an orphan. \ No newline at end of file From 99b24147e8e342ebee5054a8ef9a8346339e362a Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Mon, 29 Jan 2018 19:16:30 -0500 Subject: [PATCH 11/29] Revert "addressing dougs comments" This reverts commit 12a1a224d39ce022f5e71e1ee03a9fad5b371c1c. --- spec.md | 402 ++++++++++++++++++++++++++++---------------------------- 1 file changed, 203 insertions(+), 199 deletions(-) diff --git a/spec.md b/spec.md index e8550ea0..f855706e 100644 --- a/spec.md +++ b/spec.md @@ -26,6 +26,7 @@ - [Unbinding](#unbinding) - [Deprovisioning](#deprovisioning) - [Orphans](#orphans) + - [Extensions](#extensions) ## API Overview @@ -254,10 +255,10 @@ include additional fields within the response. When adding new fields, Service Brokers SHOULD use a unique prefix for the field names to reduce the chances of conflict with future specification defined fields. -| Response Field | Type | Description | -| -------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | -| error | string | A single word in camel case that uniquely identifies the error condition. If present, MUST be a non-empty string. | -| description | string | A user-facing error message explaining why the request failed. If present, MUST be a non-empty string. | +| Response Field | Type | Description | +| --- | --- | --- | +| error | string | A single word in camel case that uniquely identifies the error condition. If present, MUST be a non-empty string. | +| description | string | A user-facing error message explaining why the request failed. If present, MUST be a non-empty string. | ### Error Codes @@ -265,11 +266,11 @@ There are failure scenarios described throughout this specification for which the `error` field MUST contain a specific string. Service Broker authors MUST use these error codes for the specified failure scenarios. -| Error | Reason | Expected Action | -| ---------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -| AsyncRequired | This request requires client support for asynchronous service operations. | The query parameter `accepts_incomplete=true` MUST be included the request. | +| Error | Reason | Expected Action | +| --- | --- | --- | +| AsyncRequired | This request requires client support for asynchronous service operations. | The query parameter `accepts_incomplete=true` MUST be included the request. | | ConcurrencyError | The Service Broker does not support concurrent requests that mutate the same resource. | Clients MUST wait until pending requests have completed for the specified resources. | -| RequiresApp | The request body is missing the `app_guid` field. | The `app_guid` MUST be included in the request body. | +| RequiresApp | The request body is missing the `app_guid` field. | The `app_guid` MUST be included in the request body. | ## Catalog Management @@ -313,8 +314,8 @@ Broker API. The following HTTP Headers are defined for this operation: -| Header | Type | Description | -| --------------------------------------- | --------- | ----------------------------------------------------------------------------------------- | +| Header | Type | Description | +| --- | --- | --- | | X-Broker-API-Version* | string | See [API Version Header](#api-version-header). | \* Headers with an asterisk are REQUIRED. @@ -326,9 +327,9 @@ $ curl http://username:password@service-broker-url/v2/catalog -H "X-Broker-API-V ### Response -| Status Code | Description | -| ----------- | ------------------------------------------------------------------------------------------------- | -| 200 OK | MUST be returned upon successful processing of this request. The expected response body is below. | +| Status Code | Description | +| --- | --- | +| 200 OK | MUST be returned upon successful processing of this request. The expected response body is below. | #### Body @@ -343,26 +344,26 @@ the use of CLI-unfriendly strings that might cause problems for command line parsers (or that are not very meaningful to users), such as `-`. It is therefore RECOMMENDED that implementations avoid such strings. -| Response field | Type | Description | -| -------------- | ------------------------ | ------------------------------------------------------ | -| services* | array-of-service-objects | Schema of service objects defined below. MAY be empty. | +| Response field | Type | Description | +| --- | --- | --- | +| services* | array-of-service-objects | Schema of service objects defined below. MAY be empty. | \* Fields with an asterisk are REQUIRED. ##### Service Objects -| Response field | Type | Description | -| -------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| name* | string | A CLI-friendly name of the service. MUST only contain lowercase characters, numbers and hyphens (no spaces). MUST be unique across all service objects returned in this response. MUST be a non-empty string. | -| id* | string | An identifier used to correlate this service in future requests to the Service Broker. This MUST be globally unique. MUST be a non-empty string. Using a GUID is RECOMMENDED. | -| description* | string | A short description of the service. MUST be a non-empty string. | -| tags | array-of-strings | Tags provide a flexible mechanism to expose a classification, attribute, or base technology of a service, enabling equivalent services to be swapped out without changes to dependent logic in applications, buildpacks, or other services. E.g. mysql, relational, redis, key-value, caching, messaging, amqp. | -| requires | array-of-strings | A list of permissions that the user would have to give the service, if they provision it. The only permissions currently supported are `syslog_drain`, `route_forwarding` and `volume_mount`. | -| bindable* | boolean | Specifies whether Service Instances of the service can be bound to applications. This specifies the default for all plans of this service. Plans can override this field (see [Plan Object](#plan-object)). | -| metadata | object | An opaque object of metadata for a Service Offering. Controller treats this as a blob. Note that there are [conventions](profile.md#service-metadata) in existing Service Brokers and controllers for fields that aid in the display of catalog data. | -| [dashboard_client](#dashboard-client-object) | object | Contains the data necessary to activate the Dashboard SSO feature for this service. | -| plan_updateable | boolean | Whether the service supports upgrade/downgrade for some plans. Please note that the misspelling of the attribute `plan_updatable` as `plan_updateable` was done by mistake. We have opted to keep that misspelling instead of fixing it and thus breaking backward compatibility. Defaults to false. | -| [plans*](#plan-object) | array-of-objects | A list of plans for this service, schema is defined below. MUST contain at least one plan. | +| Response field | Type | Description | +| --- | --- | --- | +| name* | string | A CLI-friendly name of the service. MUST only contain lowercase characters, numbers and hyphens (no spaces). MUST be unique across all service objects returned in this response. MUST be a non-empty string. | +| id* | string | An identifier used to correlate this service in future requests to the Service Broker. This MUST be globally unique. MUST be a non-empty string. Using a GUID is RECOMMENDED. | +| description* | string | A short description of the service. MUST be a non-empty string. | +| tags | array-of-strings | Tags provide a flexible mechanism to expose a classification, attribute, or base technology of a service, enabling equivalent services to be swapped out without changes to dependent logic in applications, buildpacks, or other services. E.g. mysql, relational, redis, key-value, caching, messaging, amqp. | +| requires | array-of-strings | A list of permissions that the user would have to give the service, if they provision it. The only permissions currently supported are `syslog_drain`, `route_forwarding` and `volume_mount`. | +| bindable* | boolean | Specifies whether Service Instances of the service can be bound to applications. This specifies the default for all plans of this service. Plans can override this field (see [Plan Object](#plan-object)). | +| metadata | object | An opaque object of metadata for a Service Offering. Controller treats this as a blob. Note that there are [conventions](profile.md#service-metadata) in existing Service Brokers and controllers for fields that aid in the display of catalog data. | +| [dashboard_client](#dashboard-client-object) | object | Contains the data necessary to activate the Dashboard SSO feature for this service. | +| plan_updateable | boolean | Whether the service supports upgrade/downgrade for some plans. Please note that the misspelling of the attribute `plan_updatable` as `plan_updateable` was done by mistake. We have opted to keep that misspelling instead of fixing it and thus breaking backward compatibility. Defaults to false. | +| [plans*](#plan-object) | array-of-objects | A list of plans for this service, schema is defined below. MUST contain at least one plan. | \* Fields with an asterisk are REQUIRED. @@ -377,52 +378,52 @@ how Platforms might expose these values to their users. ##### Dashboard Client Object -| Response field | Type | Description | -| -------------- | ------ | --------------------------------------------------------------------------------------------------------- | -| id | string | The id of the Oauth client that the dashboard will use. If present, MUST be a non-empty string. | -| secret | string | A secret for the dashboard client. If present, MUST be a non-empty string. | -| redirect_uri | string | A URI for the service dashboard. Validated by the OAuth token server when the dashboard requests a token. | +| Response field | Type | Description | +| --- | --- | --- | +| id | string | The id of the Oauth client that the dashboard will use. If present, MUST be a non-empty string. | +| secret | string | A secret for the dashboard client. If present, MUST be a non-empty string. | +| redirect_uri | string | A URI for the service dashboard. Validated by the OAuth token server when the dashboard requests a token. | ##### Plan Object -| Response field | Type | Description | -| ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| id* | string | An identifier used to correlate this plan in future requests to the Service Broker. This MUST be globally unique. MUST be a non-empty string. Using a GUID is RECOMMENDED. | -| name* | string | The CLI-friendly name of the plan. MUST only contain lowercase characters, numbers and hyphens (no spaces). MUST be unique within the service. MUST be a non-empty string. | -| description* | string | A short description of the plan. MUST be a non-empty string. | -| metadata | object | An opaque object of metadata for a Service Plan. Controller treats this as a blob. Note that there are [conventions](profile.md#service-metadata) in existing Service Brokers and controllers for fields that aid in the display of catalog data. | -| free | boolean | When false, Service Instances of this plan have a cost. The default is true. | -| bindable | boolean | Specifies whether Service Instances of the Service Plan can be bound to applications. This field is OPTIONAL. If specified, this takes precedence over the `bindable` attribute of the service. If not specified, the default is derived from the service. | -| [schemas](#schema-object) | object | Schema definitions for Service Instances and bindings for the plan. | +| Response field | Type | Description | +| --- | --- | --- | +| id* | string | An identifier used to correlate this plan in future requests to the Service Broker. This MUST be globally unique. MUST be a non-empty string. Using a GUID is RECOMMENDED. | +| name* | string | The CLI-friendly name of the plan. MUST only contain lowercase characters, numbers and hyphens (no spaces). MUST be unique within the service. MUST be a non-empty string. | +| description* | string | A short description of the plan. MUST be a non-empty string. | +| metadata | object | An opaque object of metadata for a Service Plan. Controller treats this as a blob. Note that there are [conventions](profile.md#service-metadata) in existing Service Brokers and controllers for fields that aid in the display of catalog data. | +| free | boolean | When false, Service Instances of this plan have a cost. The default is true. | +| bindable | boolean | Specifies whether Service Instances of the Service Plan can be bound to applications. This field is OPTIONAL. If specified, this takes precedence over the `bindable` attribute of the service. If not specified, the default is derived from the service. | +| [schemas](#schema-object) | object | Schema definitions for Service Instances and bindings for the plan. | \* Fields with an asterisk are REQUIRED. ##### Schema Object -| Response field | Type | Description | -| -------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------ | -| [service_instance](#service-instance-object) | object | The schema definitions for creating and updating a Service Instance. | -| [service_binding](#service-binding-object) | object | The schema definition for creating a Service Binding. Used only if the Service Plan is bindable. | +| Response field | Type | Description | +| --- | --- | --- | +| [service_instance](#service-instance-object) | object | The schema definitions for creating and updating a Service Instance. | +| [service_binding](#service-binding-object) | object | The schema definition for creating a Service Binding. Used only if the Service Plan is bindable. | ##### Service Instance Object -| Response field | Type | Description | -| ---------------------------------- | ------ | ------------------------------------------------------ | +| Response field | Type | Description | +| --- | --- | --- | | [create](#input-parameters-object) | object | The schema definition for creating a Service Instance. | | [update](#input-parameters-object) | object | The schema definition for updating a Service Instance. | ##### Service Binding Object -| Response field | Type | Description | -| ---------------------------------- | ------ | ----------------------------------------------------- | +| Response field | Type | Description | +| --- | --- | --- | | [create](#input-parameters-object) | object | The schema definition for creating a Service Binding. | ##### Input Parameters Object -| Response field | Type | Description | -| -------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------- | -| parameters | JSON schema object | The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object. | +| Response field | Type | Description | +| --- | --- | --- | +| parameters | JSON schema object | The schema definition for the input parameters. Each input parameter is expressed as a property within a JSON object. | The following rules apply if `parameters` is included anywhere in the catalog: * Platforms MUST support at least @@ -670,11 +671,11 @@ to provide additional detail for users about the progress of the operation. The request provides these query string parameters as useful hints for Service Brokers. -| Query-String Field | Type | Description | -| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| service_id | string | If present, it MUST be the ID of the service being used. | -| plan_id | string | If present, it MUST be the ID of the plan for the service being use. | -| operation | string | A Service Broker-provided identifier for the operation. When a value for `operation` is included with asynchronous responses for [Provision](#provisioning), [Update](#updating-a-service-instance), and [Deprovision](#deprovisioning) requests, the Platform MUST provide the same value using this query parameter as a percent-encoded string. If present, MUST be a non-empty string. | +| Query-String Field | Type | Description | +| --- | --- | --- | +| service_id | string | If present, it MUST be the ID of the service being used. | +| plan_id | string | If present, it MUST be the ID of the plan for the service being use. | +| operation | string | A Service Broker-provided identifier for the operation. When a value for `operation` is included with asynchronous responses for [Provision](#provisioning), [Update](#updating-a-service-instance), and [Deprovision](#deprovisioning) requests, the Platform MUST provide the same value using this query parameter as a percent-encoded string. If present, MUST be a non-empty string. | Note: Although the request query parameters `service_id` and `plan_id` are not mandatory, the Platform SHOULD include them on all `last_operation` requests @@ -697,11 +698,11 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc ### Response -| Status Code | Description | -| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 200 OK | MUST be returned upon successful processing of this request. The expected response body is below. | -| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | -| 410 Gone | Appropriate only for asynchronous delete operations. The Platform MUST consider this response a success and forget about the resource. The expected response body is `{}`. Returning this while the Platform is polling for create or update operations SHOULD be interpreted as an invalid response and the Platform SHOULD continue polling. | +| Status Code | Description | +| --- | --- | +| 200 OK | MUST be returned upon successful processing of this request. The expected response body is below. | +| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | +| 410 Gone | Appropriate only for asynchronous delete operations. The Platform MUST consider this response a success and forget about the resource. The expected response body is `{}`. Returning this while the Platform is polling for create or update operations SHOULD be interpreted as an invalid response and the Platform SHOULD continue polling. | Responses with any other status code SHOULD be interpreted as an error or invalid response. The Platform SHOULD continue polling until the Service Broker @@ -712,10 +713,10 @@ returns a valid response or the For success responses, the following fields are defined: -| 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"` MUST cause the Platform to cease polling. | -| description | string | A user-facing message displayed to the Platform API client. Can be used to tell the user details about the status of the operation. If present, MUST be a non-empty string. | +| 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"` MUST cause the Platform to cease polling. | +| description | string | A user-facing message displayed to the Platform API client. Can be used to tell the user details about the status of the operation. If present, MUST be a non-empty string. | \* Fields with an asterisk are REQUIRED. @@ -756,30 +757,30 @@ This ID will be used for future requests (bind and deprovision), so the Service Broker will use it to correlate the resource it creates. #### Parameters -| Parameter name | Type | Description | -| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Parameter name | Type | Description | +| --- | --- | --- | | accepts_incomplete | boolean | A value of true indicates that the Platform and its clients support asynchronous Service Broker operations. If this parameter is not included in the request, and the Service Broker can only provision a Service Instance of the requested plan asynchronously, the Service Broker MUST reject the request with a `422 Unprocessable Entity` as described below. | #### Headers The following HTTP Headers are defined for this operation: -| Header | Type | Description | -| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| X-Broker-API-Version* | string | See [API Version Header](#api-version-header). | +| Header | Type | Description | +| --- | --- | --- | +| X-Broker-API-Version* | string | See [API Version Header](#api-version-header). | | X-Broker-API-Originating-Identity | string | See [Originating Identity](#originating-identity). | \* Headers with an asterisk are REQUIRED. #### Body -| Request field | Type | Description | -| ------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| service_id* | string | MUST be the ID of a service from the catalog for this Service Broker. | -| plan_id* | string | MUST be the ID of a plan from the service that has been requested. | -| context | object | Platform specific contextual information under which the Service Instance is to be provisioned. Although most Service Brokers will not use this field, it could be helpful in determining data placement or applying custom business rules. `context` will replace `organization_guid` and `space_guid` in future versions of the specification - in the interim both SHOULD be used to ensure interoperability with old and new implementations. | -| organization_guid* | string | Deprecated in favor of `context`. The Platform GUID for the organization under which the Service Instance is to be provisioned. Although most Service Brokers will not use this field, it might be helpful for executing operations on a user's behalf. MUST be a non-empty string. | -| space_guid* | string | Deprecated in favor of `context`. The identifier for the project space within the Platform organization. Although most Service Brokers will not use this field, it might be helpful for executing operations on a user's behalf. MUST be a non-empty string. | -| parameters | object | Configuration options for the Service Instance. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. | +| Request field | Type | Description | +| --- | --- | --- | +| service_id* | string | MUST be the ID of a service from the catalog for this Service Broker. | +| plan_id* | string | MUST be the ID of a plan from the service that has been requested. | +| context | object | Platform specific contextual information under which the Service Instance is to be provisioned. Although most Service Brokers will not use this field, it could be helpful in determining data placement or applying custom business rules. `context` will replace `organization_guid` and `space_guid` in future versions of the specification - in the interim both SHOULD be used to ensure interoperability with old and new implementations. | +| organization_guid* | string | Deprecated in favor of `context`. The Platform GUID for the organization under which the Service Instance is to be provisioned. Although most Service Brokers will not use this field, it might be helpful for executing operations on a user's behalf. MUST be a non-empty string. | +| space_guid* | string | Deprecated in favor of `context`. The identifier for the project space within the Platform organization. Although most Service Brokers will not use this field, it might be helpful for executing operations on a user's behalf. MUST be a non-empty string. | +| parameters | object | Configuration options for the Service Instance. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. | \* Fields with an asterisk are REQUIRED. @@ -820,13 +821,13 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc ### Response -| Status Code | Description | -| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 200 OK | MUST be returned if the Service Instance already exists, is fully provisioned, and the requested parameters are identical to the existing Service Instance. The expected response body is below. | -| 201 Created | MUST be returned if the Service Instance was provisioned as a result of this request. The expected response body is below. | -| 202 Accepted | MUST be returned if the Service Instance provisioning is in progress. This triggers the Platform to poll the [Service Instance Last Operation Endpoint](#polling-last-operation) for operation status. Note that a re-sent `PUT` request MUST return a `202 Accepted`, not a `200 OK`, if the Service Instance is not yet fully provisioned. | -| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | -| 409 Conflict | MUST be returned if a Service Instance with the same id already exists but with different attributes. | +| Status Code | Description | +| --- | --- | +| 200 OK | MUST be returned if the Service Instance already exists, is fully provisioned, and the requested parameters are identical to the existing Service Instance. The expected response body is below. | +| 201 Created | MUST be returned if the Service Instance was provisioned as a result of this request. The expected response body is below. | +| 202 Accepted | MUST be returned if the Service Instance provisioning is in progress. This triggers the Platform to poll the [Service Instance Last Operation Endpoint](#polling-last-operation) for operation status. Note that a re-sent `PUT` request MUST return a `202 Accepted`, not a `200 OK`, if the Service Instance is not yet fully provisioned. | +| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | +| 409 Conflict | MUST be returned if a Service Instance with the same id already exists but with different attributes. | | 422 Unprocessable Entity | MUST be returned if the Service Broker only supports asynchronous provisioning for the requested plan and the request did not include `?accepts_incomplete=true`. The response body MUST contain a response body containing error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. | Responses with any other status code will be interpreted as a failure and a @@ -837,36 +838,21 @@ being created on the Service Broker. For success responses, the following fields are defined: -| 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 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. | +| 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 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 -needed related to a Service Instance. An example of this could be lifecycle -management, (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 the servers `url` so that the Platform will know how to -invoke the endpoint(s). If the server `context` parameter of the OpenAPI -document is set to localhost the Platform can assume the extension API endpoints -are to be invoked using the Service Broker host and port. +The `extension_apis` object MAY be used to describe any additional endpoint needed related to a Service Instance. An examples of this might include backup and restore endpoints for a database. If present, MUST return a `discovery_url`. See [Extensions](#extensions) 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 Service Instance including server location, endpoints, parameters and any other detail required 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. 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. | +| Response field | Type | Description | +| --- | --- | --- | +| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail necessary for invocation. The location of the API extension endpoint(s) can be local to the Service Broker or on a remote server. The Platform MUST execute these API extensions on behalf of the client. MUST be a valid URI. See [OpenAPI](#openapi-document) 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, platforms can assume that standard broker authentication will work for the new endpoint(s). See [Extension Authentication](#extension-api-authentication) for more information. | +| adheres_to | string | A URI pointing to a specification detailing the implementation guidelines for the OpenAPI document hosted at the `discovery_url`. If present, MUST be a valid URI. | ``` @@ -877,7 +863,7 @@ are to be invoked using the Service Broker host and port. "discovery_url": "http://example-openapi-doc.example.com/extensions", "credentials":[{ "tokenURL": "https://example.com/api/oauth/token" - }], + }] "adheres_to": "http://example-specification.example.com" }] } @@ -910,8 +896,8 @@ error message in response. `:instance_id` MUST be the ID a previously provisioned Service Instance. #### Parameters -| Parameter name | Type | Description | -| ------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Parameter name | Type | Description | +| --- | --- | --- | | accepts_incomplete | boolean | A value of true indicates that the Platform and its clients support asynchronous Service Broker operations. If this parameter is not included in the request, and the Service Broker can only provision a Service Instance of the requested plan asynchronously, the Service Broker SHOULD reject the request with a `422 Unprocessable Entity` as described below. | #### Headers @@ -927,24 +913,24 @@ The following HTTP Headers are defined for this operation: #### Body -| Request Field | Type | Description | -| ------------------------------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| context | object | Contextual data under which the Service Instance is created. | -| service_id* | string | MUST be the ID of a service from the catalog for this Service Broker. | -| plan_id | string | If present, MUST be the ID of a plan from the service that has been requested. If this field is not present in the request message, then the Service Broker MUST NOT change the plan of the instance as a result of this request. | -| parameters | object | Configuration options for the Service Instance. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. See "Note" below. | -| [previous_values](#previous-values-object) | object | Information about the Service Instance prior to the update. | +| Request Field | Type | Description | +| --- | --- | --- | +| context | object | Contextual data under which the Service Instance is created. | +| service_id* | string | MUST be the ID of a service from the catalog for this Service Broker. | +| plan_id | string | If present, MUST be the ID of a plan from the service that has been requested. If this field is not present in the request message, then the Service Broker MUST NOT change the plan of the instance as a result of this request. | +| parameters | object | Configuration options for the Service Instance. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. See "Note" below. | +| [previous_values](#previous-values-object) | object | Information about the Service Instance prior to the update. | \* Fields with an asterisk are REQUIRED. ##### Previous Values Object -| Request Field | Type | Description | -| --------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| service_id | string | Deprecated; determined to be unnecessary as the value is immutable. If present, it MUST be the ID of the service for the Service Instance. | -| plan_id | string | If present, it MUST be the ID of the plan prior to the update. | +| Request Field | Type | Description | +| --- | --- | --- | +| service_id | string | Deprecated; determined to be unnecessary as the value is immutable. If present, it MUST be the ID of the service for the Service Instance. | +| plan_id | string | If present, it MUST be the ID of the plan prior to the update. | | organization_id | string | Deprecated as it was redundant information. Organization for the Service Instance MUST be provided by Platforms in the top-level field `context`. If present, it MUST be the ID of the organization specified for the Service Instance. | -| space_id | string | Deprecated as it was redundant information. Space for the Service Instance MUST be provided by Platforms in the top-level field `context`. If present, it MUST be the ID of the space specified for the Service Instance. | +| space_id | string | Deprecated as it was redundant information. Space for the Service Instance MUST be provided by Platforms in the top-level field `context`. If present, it MUST be the ID of the space specified for the Service Instance. | Note: The `parameters` specified are expected to be the values specified by an end-user. Whether the user chooses to include the complete set of @@ -1008,11 +994,11 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc ### Response -| Status Code | Description | -| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 200 OK | MUST be returned if the request's changes have been applied. The expected response body is `{}`. | -| 202 Accepted | MUST be returned if the Service Instance update is in progress. This triggers the Platform to poll the [Last Operation](#polling-last-operation) for operation status. Note that a re-sent `PATCH` request MUST return a `202 Accepted`, not a `200 OK`, if the requested update has not yet completed. | -| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | +| Status Code | Description | +| --- | --- | +| 200 OK | MUST be returned if the request's changes have been applied. The expected response body is `{}`. | +| 202 Accepted | MUST be returned if the Service Instance update is in progress. This triggers the Platform to poll the [Last Operation](#polling-last-operation) for operation status. Note that a re-sent `PATCH` request MUST return a `202 Accepted`, not a `200 OK`, if the requested update has not yet completed. | +| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | | 422 Unprocessable entity | MUST be returned if the requested change is not supported or if the request cannot currently be fulfilled due to the state of the Service Instance (e.g. Service Instance utilization is over the quota of the requested plan). Additionally, a `422 Unprocessable Entity` can also be returned if the Service Broker only supports asynchronous update for the requested plan and the request did not include `?accepts_incomplete=true`; in this case the response body MUST contain a error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. | Responses with any other status code will be interpreted as a failure. @@ -1021,9 +1007,9 @@ Responses with any other status code will be interpreted as a failure. For success responses, the following fields are defined: -| Response field | Type | Description | -| ------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 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. | +| Response field | Type | Description | +| --- | --- | --- | +| 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. | ``` { @@ -1127,14 +1113,14 @@ The following HTTP Headers are defined for this operation: #### Body -| Request Field | Type | Description | -| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| context | object | Contextual data under which the Service Binding is created. | -| service_id* | string | MUST be the ID of the service that is being used. | -| plan_id* | string | MUST be the ID of the plan from the service that is being used. | -| app_guid | string | Deprecated in favor of `bind_resource.app_guid`. GUID of an application associated with the binding to be created. If present, MUST be a non-empty string. | +| Request Field | Type | Description | +| --- | --- | --- | +| context | object | Contextual data under which the Service Binding is created. | +| service_id* | string | MUST be the ID of the service that is being used. | +| plan_id* | string | MUST be the ID of the plan from the service that is being used. | +| app_guid | string | Deprecated in favor of `bind_resource.app_guid`. GUID of an application associated with the binding to be created. If present, MUST be a non-empty string. | | bind_resource | object | A JSON object that contains data for Platform resources associated with the binding to be created. See [Bind Resource Object](#bind-resource-object) for more information. | -| parameters | object | Configuration options for the Service Binding. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. | +| parameters | object | Configuration options for the Service Binding. Service Brokers SHOULD ensure that the client has provided valid configuration parameters and values for the operation. | \* Fields with an asterisk are REQUIRED. @@ -1148,10 +1134,10 @@ request, therefore the `bind_resource` and its fields are OPTIONAL. Below are some common fields that MAY be used. Platforms MAY choose to add additional ones as needed. -| Request Field | Type | Description | -| ------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| app_guid | string | GUID of an application associated with the binding. For [credentials](#types-of-binding) bindings. MUST be unique within the scope of the Platform. | -| route | string | URL of the application to be intermediated. For [route services](#route-services) bindings. | +| Request Field | Type | Description | +| --- | --- | --- | +| app_guid | string | GUID of an application associated with the binding. For [credentials](#types-of-binding) bindings. MUST be unique within the scope of the Platform. | +| route | string | URL of the application to be intermediated. For [route services](#route-services) bindings. | `app_guid` represents the scope to which the binding will apply within the Platform. For example, in Cloud Foundry it might map to an "application" @@ -1199,12 +1185,12 @@ $ curl http://username:password@service-broker-url/v2/service_instances/:instanc ### Response -| Status Code | Description | -| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 200 OK | MUST be returned if the binding already exists and the requested parameters are identical to the existing binding. The expected response body is below. | -| 201 Created | MUST be returned if the binding was created as a result of this request. The expected response body is below. | -| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | -| 409 Conflict | MUST be returned if a Service Binding with the same id, for the same Service Instance, already exists but with different parameters. | +| Status Code | Description | +| --- | --- | +| 200 OK | MUST be returned if the binding already exists and the requested parameters are identical to the existing binding. The expected response body is below. | +| 201 Created | MUST be returned if the binding was created as a result of this request. The expected response body is below. | +| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | +| 409 Conflict | MUST be returned if a Service Binding with the same id, for the same Service Instance, already exists but with different parameters. | | 422 Unprocessable Entity | MUST be returned if the Service Broker requires that `app_guid` be included in the request body. The response body MUST contain error code `"RequiresApp"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service supports generation of credentials through binding an application only."`. Additionally, if the Service Broker rejects the request due to a concurrent request to create a binding for the same Service Instance, then this error MUST be returned (see [Blocking Operations](#blocking-operations)). | Responses with any other status code will be interpreted as a failure and an @@ -1215,22 +1201,22 @@ created on the Service Broker. For success responses, the following fields are defined: -| Response Field | Type | Description | -| ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| credentials | object | A free-form hash of credentials that can be used by applications or users to access the service. | -| syslog_drain_url | string | A URL to which logs MUST be streamed. `"requires":["syslog_drain"]` MUST be declared in the [Catalog](#catalog-management) endpoint or the Platform MUST consider the response invalid. | -| route_service_url | string | A URL to which the Platform MUST proxy requests for the address sent with `bind_resource.route` in the request body. `"requires":["route_forwarding"]` MUST be declared in the [Catalog](#catalog-management) endpoint or the Platform can consider the response invalid. | -| volume_mounts | array-of-objects | An array of configuration for remote storage devices to be mounted into an application container filesystem. `"requires":["volume_mount"]` MUST be declared in the [Catalog](#catalog-management) endpoint or the Platform can consider the response invalid. | +| Response Field | Type | Description | +| --- | --- | --- | +| credentials | object | A free-form hash of credentials that can be used by applications or users to access the service. | +| syslog_drain_url | string | A URL to which logs MUST be streamed. `"requires":["syslog_drain"]` MUST be declared in the [Catalog](#catalog-management) endpoint or the Platform MUST consider the response invalid. | +| route_service_url | string | A URL to which the Platform MUST proxy requests for the address sent with `bind_resource.route` in the request body. `"requires":["route_forwarding"]` MUST be declared in the [Catalog](#catalog-management) endpoint or the Platform can consider the response invalid. | +| volume_mounts | array-of-objects | An array of configuration for remote storage devices to be mounted into an application container filesystem. `"requires":["volume_mount"]` MUST be declared in the [Catalog](#catalog-management) endpoint or the Platform can consider the response invalid. | ##### Volume Mounts Object -| Response Field | Type | Description | -| -------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| driver* | string | Name of the volume driver plugin which manages the device. | -| container_dir* | string | The path in the application container onto which the volume will be mounted. This specification does not mandate what action the Platform is to take if the path specified already exists in the container. | -| mode* | string | "r" to mount the volume read-only or "rw" to mount it read-write. | -| device_type* | string | A string specifying the type of device to mount. Currently the only supported value is "shared". | -| device* | device-object | Device object containing device_type specific details. Currently only shared devices are supported. | +| Response Field | Type | Description | +| --- | --- | --- | +| driver* | string | Name of the volume driver plugin which manages the device. | +| container_dir* | string | The path in the application container onto which the volume will be mounted. This specification does not mandate what action the Platform is to take if the path specified already exists in the container. | +| mode* | string | "r" to mount the volume read-only or "rw" to mount it read-write. | +| device_type* | string | A string specifying the type of device to mount. Currently the only supported value is "shared". | +| device* | device-object | Device object containing device_type specific details. Currently only shared devices are supported. | \* Fields with an asterisk are REQUIRED. @@ -1239,9 +1225,9 @@ For success responses, the following fields are defined: Currently only shared devices are supported; a distributed file system which can be mounted on all app instances simultaneously. -| Field | Type | Description | -| ------------ | ------ | --------------------------------------------------------------------------- | -| volume_id* | string | ID of the shared volume to mount on every app instance. | +| Field | Type | Description | +| --- | --- | --- | +| volume_id* | string | ID of the shared volume to mount on every app instance. | | mount_config | object | Configuration object to be passed to the driver when the volume is mounted. | \* Fields with an asterisk are REQUIRED. @@ -1302,10 +1288,10 @@ Service Instance. The request provides these query string parameters as useful hints for Service Brokers. -| Query-String Field | Type | Description | -| ------------------ | ------ | ------------------------------------------------------------------------ | -| service_id* | string | MUST be the ID of the service associated with the binding being deleted. | -| plan_id* | string | MUST be the ID of the plan associated with the binding being deleted. | +| Query-String Field | Type | Description | +| --- | --- | --- | +| service_id* | string | MUST be the ID of the service associated with the binding being deleted. | +| plan_id* | string | MUST be the ID of the plan associated with the binding being deleted. | \* Query parameters with an asterisk are REQUIRED. @@ -1329,11 +1315,11 @@ $ curl 'http://username:password@service-broker-url/v2/service_instances/:instan ### Response -| Status Code | Description | -| --------------- | ------------------------------------------------------------------------------------------------------------ | -| 200 OK | MUST be returned if the binding was deleted as a result of this request. The expected response body is `{}`. | -| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | -| 410 Gone | MUST be returned if the binding does not exist. The expected response body is `{}`. | +| Status Code | Description | +| --- | --- | +| 200 OK | MUST be returned if the binding was deleted as a result of this request. The expected response body is `{}`. | +| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | +| 410 Gone | MUST be returned if the binding does not exist. The expected response body is `{}`. | Responses with any other status code will be interpreted as a failure and the Platform MUST continue to remember the Service Binding. @@ -1367,10 +1353,10 @@ The request provides these query string parameters as useful hints for Service Brokers. -| Query-String Field | Type | Description | -| ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| service_id* | string | MUST be the ID of the Service Instance being deleted. | -| plan_id* | string | MUST be the ID of the plan associated with the Service Instance being deleted. | +| Query-String Field | Type | Description | +| --- | --- | --- | +| service_id* | string | MUST be the ID of the Service Instance being deleted. | +| plan_id* | string | MUST be the ID of the plan associated with the Service Instance being deleted. | | accepts_incomplete | boolean | A value of true indicates that both the Platform and the requesting client support asynchronous deprovisioning. If this parameter is not included in the request, and the Service Broker can only deprovision a Service Instance of the requested plan asynchronously, the Service Broker MUST reject the request with a `422 Unprocessable Entity` as described below. | \* Query parameters with an asterisk are REQUIRED. @@ -1394,12 +1380,12 @@ $ curl 'http://username:password@service-broker-url/v2/service_instances/:instan ### Response -| Status Code | Description | -| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 200 OK | MUST be returned if the Service Instance was deleted as a result of this request. The expected response body is `{}`. | -| 202 Accepted | MUST be returned if the Service Instance deletion is in progress. This triggers the Platform to poll the [Service Instance Last Operation Endpoint](#polling-last-operation) for operation status. Note that a re-sent `DELETE` request MUST return a `202 Accepted`, not a `200 OK`, if the delete request has not completed yet. | -| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | -| 410 Gone | MUST be returned if the Service Instance does not exist. | +| Status Code | Description | +| --- | --- | +| 200 OK | MUST be returned if the Service Instance was deleted as a result of this request. The expected response body is `{}`. | +| 202 Accepted | MUST be returned if the Service Instance deletion is in progress. This triggers the Platform to poll the [Service Instance Last Operation Endpoint](#polling-last-operation) for operation status. Note that a re-sent `DELETE` request MUST return a `202 Accepted`, not a `200 OK`, if the delete request has not completed yet. | +| 400 Bad Request | MUST be returned if the request is malformed or missing mandatory data. | +| 410 Gone | MUST be returned if the Service Instance does not exist. | | 422 Unprocessable Entity | MUST be returned if the Service Broker only supports asynchronous deprovisioning for the requested plan and the request did not include `?accepts_incomplete=true`. The response body MUST contain error code `"AsyncRequired"` (see [Service Broker Errors](#service-broker-errors)). The error response MAY include a helpful error message in the `description` field such as `"This Service Plan requires client support for asynchronous service operations."`. | Responses with any other status code will be interpreted as a failure and the @@ -1441,18 +1427,36 @@ success. Platforms SHOULD initiate orphan mitigation in the following scenarios: | Status code of Service Broker response | Platform interpretation of response | Platform initiates orphan mitigation? | -| -------------------------------------- | ----------------------------------- | ------------------------------------- | -| 200 | Success | No | -| 200 with malformed response | Failure | No | -| 201 | Success | No | -| 201 with malformed response | Failure | Yes | -| All other 2xx | Failure | Yes | -| 408 | Timeout failure | Yes | -| All other 4xx | Request rejected | No | -| 5xx | Service Broker error | Yes | -| Timeout | Failure | Yes | +| --- | --- | --- | +| 200 | Success | No | +| 200 with malformed response | Failure | No | +| 201 | Success | No | +| 201 with malformed response | Failure | Yes | +| All other 2xx | Failure | Yes | +| 408 | Timeout failure | Yes | +| All other 4xx | Request rejected | No | +| 5xx | Service Broker error | Yes | +| Timeout | Failure | Yes | If the Platform encounters an internal error provisioning a Service Instance or Service Binding (for example, saving to the database fails), then it MUST at least send a single delete or unbind request to the Service Broker to prevent -the creation of an orphan. \ No newline at end of file +the creation of an orphan. + +## Extensions + +A Service Broker might want to extend the Service Broker API to include custom endpoints specific to their service. An example of this could be lifecycle management, (e.g. "Day Two Operations"), like Backup, Restore, Stop, Start, Restart and Pause. Extending the Service Broker API can be done on a per Service Instance basis, during provisioning. The 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. See [Provisioning](#provisioning) for more information on extensions on a per Service Instance basis. + +### OpenAPI Document + +To extend the API, the Service Broker MUST create an OpenAPI 3.0+ document describing the additional API endpoints and parameters. 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. + +### Extension API on Remote Servers + +Additional API endpoints MAY be executed on a remote server, however the OpenAPI document MUST include the servers `url` so that the Platform will know how to invoke the endpoint(s). If the server `context` parameter of the OpenAPI document is set to local host the Platform can assume the extension API endpoints are to be invoked using the Service Broker host and port. + +### Extension API Authentication + +The Service Broker MAY use the the same broker authentication method for invocation of extension endpoints by not providing credentials as part of a `extensions_api` object. If no credentials are present in an `extensions_api` object, the Platform can assume that the default broker authentication method is to be used. + +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. If credentials are present in an `extensions_api` object, the Platform will need to verify the authentication method from the OpenAPI document. From 451a78f7c7379a034c3a72ed2abc1cd566b11ffb Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Mon, 29 Jan 2018 19:24:44 -0500 Subject: [PATCH 12/29] Addressing Dougs comments. --- spec.md | 44 ++++++++++++++++++++------------------------ 1 file changed, 20 insertions(+), 24 deletions(-) diff --git a/spec.md b/spec.md index f855706e..55529bb0 100644 --- a/spec.md +++ b/spec.md @@ -26,7 +26,6 @@ - [Unbinding](#unbinding) - [Deprovisioning](#deprovisioning) - [Orphans](#orphans) - - [Extensions](#extensions) ## API Overview @@ -846,13 +845,28 @@ For success responses, the following fields are defined: ##### Extension APIs Object -The `extension_apis` object MAY be used to describe any additional endpoint needed related to a Service Instance. An examples of this might include backup and restore endpoints for a database. If present, MUST return a `discovery_url`. See [Extensions](#extensions) for more information. +The `extension_apis` object MAY be used to describe any additional endpoint +needed related to a Service Instance. An example of this could be lifecycle +management, (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 the servers `url` so that the Platform will know how to +invoke the endpoint(s). If the server `context` parameter of the OpenAPI +document is set to localhost the Platform can assume the extension API endpoints +are to be invoked using the Service Broker host and port. | Response field | Type | Description | | --- | --- | --- | -| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail necessary for invocation. The location of the API extension endpoint(s) can be local to the Service Broker or on a remote server. The Platform MUST execute these API extensions on behalf of the client. MUST be a valid URI. See [OpenAPI](#openapi-document) 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, platforms can assume that standard broker authentication will work for the new endpoint(s). See [Extension Authentication](#extension-api-authentication) for more information. | -| adheres_to | string | A URI pointing to a specification detailing the implementation guidelines for the OpenAPI document hosted at the `discovery_url`. If present, MUST be a valid URI. | +| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail required 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. 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. | ``` @@ -863,7 +877,7 @@ The `extension_apis` object MAY be used to describe any additional endpoint need "discovery_url": "http://example-openapi-doc.example.com/extensions", "credentials":[{ "tokenURL": "https://example.com/api/oauth/token" - }] + }], "adheres_to": "http://example-specification.example.com" }] } @@ -1442,21 +1456,3 @@ If the Platform encounters an internal error provisioning a Service Instance or Service Binding (for example, saving to the database fails), then it MUST at least send a single delete or unbind request to the Service Broker to prevent the creation of an orphan. - -## Extensions - -A Service Broker might want to extend the Service Broker API to include custom endpoints specific to their service. An example of this could be lifecycle management, (e.g. "Day Two Operations"), like Backup, Restore, Stop, Start, Restart and Pause. Extending the Service Broker API can be done on a per Service Instance basis, during provisioning. The 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. See [Provisioning](#provisioning) for more information on extensions on a per Service Instance basis. - -### OpenAPI Document - -To extend the API, the Service Broker MUST create an OpenAPI 3.0+ document describing the additional API endpoints and parameters. 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. - -### Extension API on Remote Servers - -Additional API endpoints MAY be executed on a remote server, however the OpenAPI document MUST include the servers `url` so that the Platform will know how to invoke the endpoint(s). If the server `context` parameter of the OpenAPI document is set to local host the Platform can assume the extension API endpoints are to be invoked using the Service Broker host and port. - -### Extension API Authentication - -The Service Broker MAY use the the same broker authentication method for invocation of extension endpoints by not providing credentials as part of a `extensions_api` object. If no credentials are present in an `extensions_api` object, the Platform can assume that the default broker authentication method is to be used. - -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. If credentials are present in an `extensions_api` object, the Platform will need to verify the authentication method from the OpenAPI document. From 2e15360cb9d1b9974f408e251cf20d51f0d7caee Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Mon, 29 Jan 2018 19:33:27 -0500 Subject: [PATCH 13/29] required/REQUIRED --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 55529bb0..6159d379 100644 --- a/spec.md +++ b/spec.md @@ -864,7 +864,7 @@ are to be invoked using the Service Broker host and port. | Response field | Type | Description | | --- | --- | --- | -| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance including server location, endpoints, parameters and any other detail required 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. | +| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance 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. 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. | From bcae8c04ccade1282cd1bd538eca2a9b1c23efa0 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Mon, 29 Jan 2018 21:02:41 -0500 Subject: [PATCH 14/29] Next step of doug recommendations. --- spec.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/spec.md b/spec.md index 6159d379..7d233d19 100644 --- a/spec.md +++ b/spec.md @@ -859,15 +859,16 @@ 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 the servers `url` so that the Platform will know how to invoke the endpoint(s). If the server `context` parameter of the OpenAPI -document is set to localhost the Platform can assume the extension API endpoints +document is set to `localhost` the Platform MUST assume the extension API endpoints are to be invoked using the Service Broker host and port. | Response field | Type | Description | | --- | --- | --- | -| discovery_url | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance 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. If credentials are present in an `extensions_api` object, the Platform will need to verify the authentication method from the OpenAPI document. | +| discovery_url* | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance 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. ``` { From 73663f5c718ac7b39b27a1e020d2f5ccf20b40c9 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Tue, 30 Jan 2018 09:16:31 -0500 Subject: [PATCH 15/29] field to Field --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 7d233d19..1cf6d91d 100644 --- a/spec.md +++ b/spec.md @@ -862,7 +862,7 @@ invoke the endpoint(s). If the server `context` parameter of the OpenAPI document is set to `localhost` the Platform MUST assume the extension API endpoints are to be invoked using the Service Broker host and port. -| Response field | Type | Description | +| Response Field | Type | Description | | --- | --- | --- | | discovery_url* | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance 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. | From f6012969b4038c67c73e3e553a9cd372e4ffb456 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Tue, 30 Jan 2018 09:41:22 -0500 Subject: [PATCH 16/29] remove 'related to a service instance' parts --- spec.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec.md b/spec.md index 1cf6d91d..b4709c40 100644 --- a/spec.md +++ b/spec.md @@ -846,9 +846,9 @@ For success responses, the following fields are defined: ##### Extension APIs Object The `extension_apis` object MAY be used to describe any additional endpoint -needed related to a Service Instance. An example of this could be lifecycle -management, (e.g. "Day Two Operations"), like Backup, Restore, Stop, Start, -Restart and Pause. +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), @@ -864,7 +864,7 @@ are to be invoked using the Service Broker host and port. | Response Field | Type | Description | | --- | --- | --- | -| discovery_url* | string | A URI pointing to a valid OpenAPI 3.0+ document describing the API extension(s) to the Service Instance 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. | +| 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. | From 0ce60754bd8ec2d06b4b1e6c20b594069f10ab8b Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Tue, 30 Jan 2018 14:22:11 -0500 Subject: [PATCH 17/29] update the remote/local server settings --- spec.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/spec.md b/spec.md index b4709c40..83dfdd87 100644 --- a/spec.md +++ b/spec.md @@ -857,10 +857,11 @@ 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 the servers `url` so that the Platform will know how to -invoke the endpoint(s). If the server `context` parameter of the OpenAPI -document is set to `localhost` the Platform MUST assume the extension API endpoints -are to be invoked using the Service Broker host and port. +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 | | --- | --- | --- | From 586a5cced53c2dcab20573d6ae0a46bdb5d098e4 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Tue, 6 Feb 2018 11:29:13 -0500 Subject: [PATCH 18/29] address Ville & add example --- spec.md | 33 +++++++++++++++++++++++---------- 1 file changed, 23 insertions(+), 10 deletions(-) diff --git a/spec.md b/spec.md index 83dfdd87..704b0d99 100644 --- a/spec.md +++ b/spec.md @@ -841,32 +841,45 @@ 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 | 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 APIs Object +##### Extension API Object -The `extension_apis` object MAY be used to describe any additional endpoint +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 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. +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), 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. +Service Broker host and port. The `url` for this Server Object MUST be an +absolute URL. + +``` +{ + "servers": [ + { + "url": "https://extensions.servicebrokerexample.com", + "description": "Service Broker Extensions Server" + } + ] +} +``` +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. | +| 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. | | 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. From d236bf4f2e47936e1c1ef881e844a6b457c4aa7c Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Tue, 6 Feb 2018 11:39:13 -0500 Subject: [PATCH 19/29] spelling on invoked, eol --- spec.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 704b0d99..88c74cf2 100644 --- a/spec.md +++ b/spec.md @@ -853,7 +853,7 @@ 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), 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 +API. As such they are indended to be invoked by the Platform on behalf of its clients. Extension API endpoints MAY be executed on a remote server, however the OpenAPI @@ -874,6 +874,7 @@ absolute URL. ] } ``` + 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 | From 8360d16dba90c3adb10afe35718bb45854e15c44 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Thu, 15 Feb 2018 12:00:14 -0500 Subject: [PATCH 20/29] add server_url --- spec.md | 24 ++++-------------------- 1 file changed, 4 insertions(+), 20 deletions(-) diff --git a/spec.md b/spec.md index 704b0d99..270336c9 100644 --- a/spec.md +++ b/spec.md @@ -851,34 +851,17 @@ 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), authentication -mechanism and server URL. The new APIs are extensions to the Open Service Broker +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. -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. The `url` for this Server Object MUST be an -absolute URL. - -``` -{ - "servers": [ - { - "url": "https://extensions.servicebrokerexample.com", - "description": "Service Broker Extensions Server" - } - ] -} -``` 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. | | 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. | @@ -890,6 +873,7 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma "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" }], From 643e47c087d0a7c7434d9b80ddec03b2e4c24a4d Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Thu, 15 Feb 2018 15:34:33 -0500 Subject: [PATCH 21/29] add alt_instance_id --- spec.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/spec.md b/spec.md index 270336c9..54cb7656 100644 --- a/spec.md +++ b/spec.md @@ -863,6 +863,7 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma | 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. @@ -877,6 +878,7 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma "credentials":[{ "tokenURL": "https://example.com/api/oauth/token" }], + "alt_instance_id": "serviceInstance", "adheres_to": "http://example-specification.example.com" }] } From 1a64f74e7117de5b7b4df07b4950b4127e74e5d9 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Fri, 16 Feb 2018 15:15:03 -0500 Subject: [PATCH 22/29] add line about paths --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 54cb7656..104fff50 100644 --- a/spec.md +++ b/spec.md @@ -860,8 +860,8 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma | 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. | +| 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. If `discovery_url` is a path, the Platform can assume it is to be called from 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 from 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, (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. | From 4adddfe3471628061f7d91da6c2b429c035902be Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Tue, 20 Feb 2018 09:51:33 -0500 Subject: [PATCH 23/29] relative to the basepath x2 --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 104fff50..41b7c4ca 100644 --- a/spec.md +++ b/spec.md @@ -860,8 +860,8 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma | 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. If `discovery_url` is a path, the Platform can assume it is to be called from 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 from the basepath of the Service Broker. | +| 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. 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, (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. | From a38ac799aa3b995a7fc3922750ce3c6493979331 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Tue, 20 Feb 2018 16:55:24 -0500 Subject: [PATCH 24/29] spelling, improve credentials, examples --- spec.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 54 insertions(+), 6 deletions(-) diff --git a/spec.md b/spec.md index 41b7c4ca..8af8d71f 100644 --- a/spec.md +++ b/spec.md @@ -853,21 +853,31 @@ 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 +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 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. 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. | +| 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, (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. | +| 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. | | 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 with extentions + ``` { "dashboard_url": "http://example-dashboard.example.com/9189kdfsk0vfnku", @@ -875,15 +885,53 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma "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" - }], + "credentials": { + "basic": { + "username": "admin", + "password": "changeme" + }, + "api_key": { + "api_key": "some_key_value" + }, + "petstore_auth": { + "token": "some_token_value" + } + }, "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" + } + } + } + } + } +``` + + ## Updating a Service Instance By implementing this endpoint, Service Broker authors can enable users to From ba5cf6c674e8956f25e019f751a1e8bc4a45ced9 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Wed, 21 Feb 2018 13:46:25 -0500 Subject: [PATCH 25/29] tag human readable ops; more examples --- spec.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 8af8d71f..008de14c 100644 --- a/spec.md +++ b/spec.md @@ -864,6 +864,7 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma | 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. @@ -876,7 +877,7 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma "operation": "task_10" } ``` -#### Provisioning with extentions +#### Provisioning response with extentions ``` { @@ -897,6 +898,10 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma "token": "some_token_value" } }, + "operation_display_names": { + "createBackup": "Take Backup", + "postRestore": "Restore Instance" + }, "alt_instance_id": "serviceInstance", "adheres_to": "http://example-specification.example.com" }] @@ -930,7 +935,19 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma } } ``` +#### OpenAPI Path Object example +``` + "post": { + "summary": "Backup Service Instance", + "operationId": "createBackup", + "responses": { + "201": { + "description": "backup response.", + } + } + } +``` ## Updating a Service Instance From eae12ed427c9816d74ddb0a5bfef0f11959902af Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Wed, 7 Mar 2018 16:48:12 -0500 Subject: [PATCH 26/29] changing name prior to removing --- spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/spec.md b/spec.md index 008de14c..770999d8 100644 --- a/spec.md +++ b/spec.md @@ -863,7 +863,7 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma | 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. | +| openapi_instance_key | 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 `openapi_instance_key` 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. | @@ -902,7 +902,7 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma "createBackup": "Take Backup", "postRestore": "Restore Instance" }, - "alt_instance_id": "serviceInstance", + "openapi_instance_key": "serviceInstance", "adheres_to": "http://example-specification.example.com" }] } From 750bdcf05d862c6093286bc29b5a16857868fd48 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Wed, 7 Mar 2018 17:01:44 -0500 Subject: [PATCH 27/29] statement on local disc_url --- spec.md | 22 +--------------------- 1 file changed, 1 insertion(+), 21 deletions(-) diff --git a/spec.md b/spec.md index 770999d8..b9c3fc45 100644 --- a/spec.md +++ b/spec.md @@ -860,11 +860,9 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma | 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. | +| 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 local to the Service Broker the same authentication method for normal Serivce Broker calls MUST be used. 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. | -| openapi_instance_key | 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 `openapi_instance_key` 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. @@ -898,11 +896,6 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma "token": "some_token_value" } }, - "operation_display_names": { - "createBackup": "Take Backup", - "postRestore": "Restore Instance" - }, - "openapi_instance_key": "serviceInstance", "adheres_to": "http://example-specification.example.com" }] } @@ -935,19 +928,6 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma } } ``` -#### OpenAPI Path Object example - -``` - "post": { - "summary": "Backup Service Instance", - "operationId": "createBackup", - "responses": { - "201": { - "description": "backup response.", - } - } - } -``` ## Updating a Service Instance From ce8cab7835fa29949363901a72331e405f99269d Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Wed, 7 Mar 2018 17:05:22 -0500 Subject: [PATCH 28/29] +paths objects --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index b9c3fc45..9c395ea2 100644 --- a/spec.md +++ b/spec.md @@ -861,7 +861,7 @@ See [OpenAPI Server Object](https://github.com/OAI/OpenAPI-Specification/blob/ma | 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 local to the Service Broker the same authentication method for normal Serivce Broker calls MUST be used. 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. | +| 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 [Paths Objects](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#pathsObject) 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. | | 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. | From 480c4ac7b29cc95a0cb393447543130e1150fd60 Mon Sep 17 00:00:00 2001 From: Michael Rhodes Date: Wed, 7 Mar 2018 17:13:50 -0500 Subject: [PATCH 29/29] align with pr 459 --- spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec.md b/spec.md index 9c395ea2..7ed4d8f2 100644 --- a/spec.md +++ b/spec.md @@ -841,7 +841,7 @@ 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_apis | array of [Extension API](#extension-api-object) 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